Merge pull request #10 from Denperidge-Redpencil/docstring-rework

README helper functions are now generated

Author: erikap

README.md

@@ -51,79 +51,219 @@ example docker-compose parameters:
 ```
 
 ### Helper methods
+<a id="helpers.generate_uuid"></a>
 
-The template provides the user with several helper methods. They aim to give you a step ahead for:
+#### `generate_uuid`
 
-- logging
-- JSONAPI-compliancy
-- SPARQL querying
+```python
+def generate_uuid()
+```
 
-The below helpers can be imported from the `helpers` module. For example:
-```py
-from helpers import *
+> Generates a random unique user id (UUID) based on the host ID and current time
+
+<a id="helpers.log"></a>
+
+#### `log`
+
+```python
+def log(msg, *args, **kwargs)
 ```
-Available functions:
-#### log(msg)
 
-Works exactly the same as the [logging.info](https://docs.python.org/3/library/logging.html#logging.info) method from pythons' logging module.
-Logs are written to the /logs directory in the docker container.  
-Note that the `helpers` module also exposes `logger`, which is the [logger instance](https://docs.python.org/3/library/logging.html#logger-objects) used by the template. The methods provided by this instance can be used for more fine-grained logging.
+> Write a log message to the log file.
+> 
+> Works exactly the same as the logging.info (https://docs.python.org/3/library/logging.html#logging.info) method from pythons' logging module.
+> Logs are written to the /logs directory in the docker container.  
+> 
+> Note that the `helpers` module also exposes `logger`, which is the logger instance (https://docs.python.org/3/library/logging.html#logger-objects) 
+> used by the template. The methods provided by this instance can be used for more fine-grained logging.
 
-#### generate_uuid()
+<a id="helpers.error"></a>
 
-Generate a random UUID (String).
+#### `error`
 
-#### session_id_header(request)
+```python
+def error(msg, status=400, **kwargs)
+```
 
-Get the session id from the HTTP request headers.
+> Returns a Response object containing a JSONAPI compliant error response with the given status code (400 by default).
+> 
+> Response object documentation: https://flask.palletsprojects.com/en/1.1.x/api/#response-objects
+> The kwargs can be any other key supported by JSONAPI error objects: https://jsonapi.org/format/#error-objects
 
-#### rewrite_url_header(request)
+<a id="helpers.session_id_header"></a>
 
-Get the rewrite URL from the HTTP request headers.
+#### `session_id_header`
 
-#### validate_json_api_content_type(request)
+```python
+def session_id_header(request)
+```
 
-Validate whether the Content-Type header contains the JSONAPI `content-type`-header. Returns a 400 otherwise.
+> Returns the MU-SESSION-ID header from the given requests' headers
 
-#### validate_resource_type(expected_type, data)
+<a id="helpers.rewrite_url_header"></a>
 
-Validate whether the type specified in the JSONAPI data is equal to the expected type. Returns a 409 otherwise.
+#### `rewrite_url_header`
 
-#### error(title, status=400, **kwargs)
+```python
+def rewrite_url_header(request)
+```
+
+> Returns the X-REWRITE-URL header from the given requests' headers
 
-Returns a JSONAPI compliant error [Response object](https://flask.palletsprojects.com/en/1.1.x/api/#response-objects) with the given status code (default: 400). `kwargs` can be any other keys supported by [JSONAPI error objects](https://jsonapi.org/format/#error-objects).
+<a id="helpers.validate_json_api_content_type"></a>
 
-#### query(query)
+#### `validate_json_api_content_type`
 
-Executes the given SPARQL select/ask/construct query.
+```python
+def validate_json_api_content_type(request)
+```
 
-#### update(query)
+> Validate whether the request contains the JSONAPI content-type header (application/vnd.api+json). Returns a 404 otherwise
 
-Executes the given SPARQL update query.
+<a id="helpers.validate_resource_type"></a>
 
+#### `validate_resource_type`
 
-The template provides one other helper module, being the `escape_helpers`-module. It contains functions for SPARQL query-escaping. Example import:
-```py
-from escape_helpers import *
+```python
+def validate_resource_type(expected_type, data)
 ```
 
- Available functions:
-#### sparql_escape ; sparql_escape_{string|uri|date|datetime|time|bool|int|float}(value)
+> Validate whether the type specified in the JSON data is equal to the expected type. Returns a `409` otherwise.
+
+<a id="helpers.query"></a>
+
+#### `query`
+
+```python
+def query(the_query)
+```
 
-Converts the given object to a SPARQL-safe RDF object string with the right RDF-datatype.  
-This functions should be used especially when inserting user-input to avoid SPARQL-injection.
+> Execute the given SPARQL query (select/ask/construct) on the triplestore and returns the results in the given return Format (JSON by default).
 
-Separate functions are available for different python datatypes, the `sparql_escape` function however can automatically select the right method to use, for following Python  datatypes:
+<a id="helpers.update"></a>
+
+#### `update`
+
+```python
+def update(the_query)
+```
+
+> Execute the given update SPARQL query on the triplestore. If the given query is not an update query, nothing happens.
+
+<a id="helpers.update_modified"></a>
+
+#### `update_modified`
+
+```python
+def update_modified(subject, modified=datetime.datetime.now())
+```
+
+> (DEPRECATED) Executes a SPARQL query to update the modification date of the given subject URI (string).
+> The default date is now.
+
+<a id="escape_helpers.sparql_escape_string"></a>
+
+#### `sparql_escape_string`
+
+```python
+def sparql_escape_string(obj)
+```
+
+> Converts the given string to a SPARQL-safe RDF object string with the right RDF-datatype.
+
+<a id="escape_helpers.sparql_escape_datetime"></a>
+
+#### `sparql_escape_datetime`
+
+```python
+def sparql_escape_datetime(obj)
+```
 
-- `str`
-- `int`
-- `float`
-- `datetime.datetime`
-- `datetime.date`
-- `datetime.time`
-- `boolean`
+> Converts the given datetime to a SPARQL-safe RDF object string with the right RDF-datatype.
 
-The `sparql_escape_uri`-function can be used for escaping URI's.
+<a id="escape_helpers.sparql_escape_date"></a>
+
+#### `sparql_escape_date`
+
+```python
+def sparql_escape_date(obj)
+```
+
+> Converts the given date to a SPARQL-safe RDF object string with the right RDF-datatype.
+
+<a id="escape_helpers.sparql_escape_time"></a>
+
+#### `sparql_escape_time`
+
+```python
+def sparql_escape_time(obj)
+```
+
+> Converts the given time to a SPARQL-safe RDF object string with the right RDF-datatype.
+
+<a id="escape_helpers.sparql_escape_int"></a>
+
+#### `sparql_escape_int`
+
+```python
+def sparql_escape_int(obj)
+```
+
+> Converts the given int to a SPARQL-safe RDF object string with the right RDF-datatype.
+
+<a id="escape_helpers.sparql_escape_float"></a>
+
+#### `sparql_escape_float`
+
+```python
+def sparql_escape_float(obj)
+```
+
+> Converts the given float to a SPARQL-safe RDF object string with the right RDF-datatype.
+
+<a id="escape_helpers.sparql_escape_bool"></a>
+
+#### `sparql_escape_bool`
+
+```python
+def sparql_escape_bool(obj)
+```
+
+> Converts the given bool to a SPARQL-safe RDF object string with the right RDF-datatype.
+
+<a id="escape_helpers.sparql_escape_uri"></a>
+
+#### `sparql_escape_uri`
+
+```python
+def sparql_escape_uri(obj)
+```
+
+> Converts the given URI to a SPARQL-safe RDF object string with the right RDF-datatype.
+
+<a id="escape_helpers.sparql_escape"></a>
+
+#### `sparql_escape`
+
+```python
+def sparql_escape(obj)
+```
+
+> Converts the given object to a SPARQL-safe RDF object string with the right RDF-datatype. 
+> 
+> These functions should be used especially when inserting user-input to avoid SPARQL-injection.
+> Separate functions are available for different python datatypes.
+> The `sparql_escape` function however can automatically select the right method to use, for the following Python datatypes:
+> 
+> - `str`
+> - `int`
+> - `float`
+> - `datetime.datetime`
+> - `datetime.date`
+> - `datetime.time`
+> - `boolean`
+> 
+> The `sparql_escape_uri`-function can be used for escaping URI's.
 
 ### Writing SPARQL Queries
 
@@ -183,3 +323,14 @@ Since this template is based on the meinheld-gunicorn-docker image, all possible
 ### Production
 
 For hosting the app in a production setting, the template depends on [meinheld-gunicorn-docker](https://github.com/tiangolo/meinheld-gunicorn-docker). All [environment variables](https://github.com/tiangolo/meinheld-gunicorn-docker#environment-variables) used by meinheld-gunicorn can be used to configure your service as well.
+
+## Other
+### readme.py
+To simplify documenting the helper functions, `README.py` can be used to import & render the docstrings into README.md.
+Usage:
+```python3
+python3 -m pip install pydoc-markdown
+python3 README.py
+```
+You can customise the output through the API configuration! See [README.py](README.py) && the [pydoc-markdown docs](https://niklasrosenstein.github.io/pydoc-markdown/).
+

README.py

@@ -0,0 +1,48 @@
+from re import search, RegexFlag
+
+from pydoc_markdown.interfaces import Context
+from pydoc_markdown.contrib.loaders.python import PythonLoader
+from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer, MarkdownReferenceResolver
+from pydoc_markdown.contrib.processors.filter import FilterProcessor
+
+"""
+This script:
+- Extracts & renders docstrings from helpers & escape_helpers
+- Inserts that render into README.md in the right position, replacing the previous docstrings but nothing else
+"""
+
+def open_readme(mode="r"):
+    return open("README.md", mode=mode, encoding="UTF-8")
+
+if __name__ == "__main__":
+
+    context = Context(directory=".")
+    loader = PythonLoader(modules=["helpers", "escape_helpers"])
+    renderer = MarkdownRenderer(render_module_header=False, insert_header_anchors=True, code_headers=True, render_typehint_in_data_header=True, docstrings_as_blockquote=True)
+
+    loader.init(context)
+    renderer.init(context)
+
+    # https://github.com/ahopkins/mayim/blob/main/build_api_docs.py#L256
+    modules = list(loader.load())
+
+    resolver = MarkdownReferenceResolver()
+
+    # https://github.com/NiklasRosenstein/pydoc-markdown/discussions/263#discussioncomment-3409760
+    processor = FilterProcessor()
+    processor.process(modules, resolver=resolver)
+
+    doc_string = renderer.render_to_string(modules)
+
+
+    with open_readme("r") as readme:
+        old_contents = readme.read()
+        to_replace = search(r"### Helper methods((.|\n)*?)^###[^#]", old_contents, RegexFlag.MULTILINE).group(1)
+
+
+        new_contents = old_contents.replace(to_replace, "\n" + doc_string)
+
+    with open_readme("w") as readme:
+        readme.write(new_contents)
+        
+