reliqua 0.0.6__tar.gz

reliqua-0.0.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Terrence Meiczinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reliqua-0.0.6/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.2
+Name: reliqua
+Version: 0.0.6
+Summary: Simple, efficient, intuitive API Framework
+Author-email: Terrence Meiczinger <terrence72@gmail.com>
+License: MIT
+Project-URL: homepage, https://github.com/tmeiczin/reliqua
+Project-URL: documentation, https://github.com/tmeiczin/reliqua
+Project-URL: repository, https://github.com/tmeiczin/reliqua
+Keywords: utilities
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Unix
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: falcon>=3.0.0
+Requires-Dist: falcon-cors
+Requires-Dist: gunicorn>=19.6.0
+Provides-Extra: dev
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Requires-Dist: bump2version; extra == "dev"
+
+This is sample template to create a quick Python Falcon API application. It uses a schema defined in the resource for the route path and OpenAPI documentation. The base application will handle creating the routes and documentation automatically at runtime.
+
+You define a resource and the documentation will be auto-generated at startup using the docstrings.
+
+```python
+
+from reliqua.resources.base import Resource
+from reliqua import status_codes as status
+
+
+class User(Resource):
+
+    __routes__ = [
+        '/users/{id}',
+    ]
+
+    phone = phone
+
+    def on_get(self, req, resp, id=None):
+        """
+        Retrieve a user. This value
+        is awesome
+
+        :param str id:       [in=path, required] User ID
+        :param str email:    [in=query] User Email
+        :param str phone:    [in=query, enum] Phone Numbers
+
+        :response 200:
+        :response 400:
+
+        :return json:
+        """
+        try:
+            resp.media = users[int(id)]
+        except IndexError:
+            resp.status = status.HTTP_404
+
+    def on_delete(self, req, resp, id=None):
+        try:
+            users.pop(int(id))
+            resp.media = {'success': True}
+        except IndexError
+            resp.status = status.HTTP_400
+```
+
+This will create the /users/{id} endpoint and corresponding API documentation. The OpenAPI documentation and swagger.json will be dynamically generate at application startup. The OpenAPI ui will be available at:
+
+```
+http://<api-url>/docs/
+```
+
+and the swagger.json file located at:
+
+```
+http://<api-url>/docs/swagger.json
+```
+
+To create an application, you import the application template.
+
+```python
+from reliqua.app import Application
+
+    
+app = Application(
+    bind='0.0.0.0:8000',
+    proxy_api_url = 'http://example.com/api',
+    workers=1,
+    resource_path='/var/www/html/resources'
+)
+app.run()
+```
+
+```
+Where:
+
+bind:           Address and port to listen for requests. [host:port]
+proxy_api_url:  The URL to the API when being used with a proxy, like nginx. If not supplied,
+                then the bind address is used.
+workers:        Number of worker threads to start.
+resource_path:  This is where your python resource files are located.
+```
+
+Refer to the example application for more examples. You can install the library and example application
+
+```
+python setup.py install
+```
+
+You can execute the example application
+
+```
+$ reliqua-example 
+```
+
+From here the openapi-ui will be available at
+
+````
+http://localhost:8000/docs/
+````

reliqua-0.0.6/README.md

@@ -0,0 +1,99 @@
+This is sample template to create a quick Python Falcon API application. It uses a schema defined in the resource for the route path and OpenAPI documentation. The base application will handle creating the routes and documentation automatically at runtime.
+
+You define a resource and the documentation will be auto-generated at startup using the docstrings.
+
+```python
+
+from reliqua.resources.base import Resource
+from reliqua import status_codes as status
+
+
+class User(Resource):
+
+    __routes__ = [
+        '/users/{id}',
+    ]
+
+    phone = phone
+
+    def on_get(self, req, resp, id=None):
+        """
+        Retrieve a user. This value
+        is awesome
+
+        :param str id:       [in=path, required] User ID
+        :param str email:    [in=query] User Email
+        :param str phone:    [in=query, enum] Phone Numbers
+
+        :response 200:
+        :response 400:
+
+        :return json:
+        """
+        try:
+            resp.media = users[int(id)]
+        except IndexError:
+            resp.status = status.HTTP_404
+
+    def on_delete(self, req, resp, id=None):
+        try:
+            users.pop(int(id))
+            resp.media = {'success': True}
+        except IndexError
+            resp.status = status.HTTP_400
+```
+
+This will create the /users/{id} endpoint and corresponding API documentation. The OpenAPI documentation and swagger.json will be dynamically generate at application startup. The OpenAPI ui will be available at:
+
+```
+http://<api-url>/docs/
+```
+
+and the swagger.json file located at:
+
+```
+http://<api-url>/docs/swagger.json
+```
+
+To create an application, you import the application template.
+
+```python
+from reliqua.app import Application
+
+    
+app = Application(
+    bind='0.0.0.0:8000',
+    proxy_api_url = 'http://example.com/api',
+    workers=1,
+    resource_path='/var/www/html/resources'
+)
+app.run()
+```
+
+```
+Where:
+
+bind:           Address and port to listen for requests. [host:port]
+proxy_api_url:  The URL to the API when being used with a proxy, like nginx. If not supplied,
+                then the bind address is used.
+workers:        Number of worker threads to start.
+resource_path:  This is where your python resource files are located.
+```
+
+Refer to the example application for more examples. You can install the library and example application
+
+```
+python setup.py install
+```
+
+You can execute the example application
+
+```
+$ reliqua-example 
+```
+
+From here the openapi-ui will be available at
+
+````
+http://localhost:8000/docs/
+````

reliqua-0.0.6/pyproject.toml

@@ -0,0 +1,175 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+    "setuptools",
+    "wheel"
+]
+
+[project]
+name = "reliqua"
+version = "0.0.6"
+description = "Simple, efficient, intuitive API Framework"
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["utilities"]
+license = { text = "MIT" }
+authors = [
+    {name = "Terrence Meiczinger", email = "terrence72@gmail.com"}
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: Unix",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "falcon>=3.0.0",
+    "falcon-cors",
+    "gunicorn>=19.6.0",
+]
+
+[project.urls]
+homepage = "https://github.com/tmeiczin/reliqua"
+documentation = "https://github.com/tmeiczin/reliqua"
+repository = "https://github.com/tmeiczin/reliqua"
+
+[project.optional-dependencies]
+dev = [
+    "tox",
+    "requests",
+    "bump2version"
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 120
+target-version = ["py310"]
+include = '\.pyi?$'
+
+[tool.pydocstyle]
+convention = "pep257"
+add-ignore = "D412"
+# D412: No blank lines allowed between a section header and its content
+#       [required by Sphinx for ".. code:: <lang>" blocks]
+
+[tool.pylint."messages control"]
+disable = [
+    "too-many-instance-attributes",
+    "too-many-arguments",
+    "too-few-public-methods",
+    "too-many-locals",
+    "too-many-public-methods",
+    "consider-using-with",
+    "too-many-lines",
+    "too-many-branches",
+    "duplicate-code",
+    "raw-checker-failed",
+    "bad-inline-option",
+    "locally-disabled",
+    "file-ignored",
+    "suppressed-message",
+    "useless-suppression",
+    "deprecated-pragma",
+    "use-symbolic-message-instead",
+    "fixme",
+]
+max-line-length = 120
+
+[tool.pylint.BASIC]
+good-names = "i, j, k, v, r, x, y, db, fh, id, ip, st, mt, ex, Run, _"
+allowed-redefined-builtins = "id,"
+
+[tool.pylint.MAIN]
+extension-pkg-allow-list = "falcon,tesserocr"
+
+[tool.pylint.FORMAT]
+ignore-long-lines = "^.*https?://.*$"
+
+[tool.isort]
+multi_line_output = 3
+py_version = 310
+include_trailing_comma = true
+
+[tool.ruff]
+target-version = "py38"
+line-length = 120
+output-format = "full"
+exclude = [".git", ".venv", ".tox", ".dist", "doc", "*egg,build", "*.pyc"]
+
+[tool.ruff.lint]
+select = [
+  "ALL",
+]
+ignore = [
+  "A",        # flake8-builtins
+  "ANN",      # flake8-annotations
+  "ARG",      # flake8-unused-arguments
+  "B904",     # flake8-bugbear raise-without-from-inside-except
+  "BLE",      # flake8-blind-except blind-except
+  "EM",       # flake8-errmsg
+  "ERA",      # eradicate commented-out-code
+  "FIX002",   # flake8-fixme line-contains-todo
+  "FIX003",   # flake8-fixme line-contains-xxx
+  "FBT",      # flake8-boolean-trap
+  "G",        # flake8-logging-format
+  "PIE",      # flake8-pie
+  "C901",     # too-complex
+  "COM812",   # trailing-comma
+  "UP015",    # pyupgrade redundant-open-modes
+  "E501",     # line length
+  "D412",     # pydocstyle blank-lines-between-header-and-content
+  "N818",     # pep8-naming error-suffix-on-exception-name
+  "G010",     # false positive warning (check is confused between our logger and python logging)
+  "PERF203",  # try/except in for loop (this is minor issue and 3.11 added zero-cost exceptions)
+  "PLR0912",  # pylint too-many-branches
+  "PLR0913",  # pylint too-many-arguments
+  "PLR2004",  # pylint magic-value-comparison
+  "PLC1901",  # pylint compare-to-empty-string
+  "PLW2901",  # pylint redefined-loop-name
+  "PTH",      # flake8-use-pathlib
+  "RUF012",   # ruff mutable-class-default
+  "S105",     # flake8-bandit hardcoded-password-string
+  "S107",     # flake8-bandit hardcoded-password-default
+  "S108",     # flake8-bandit hardcoded-temp-file
+  "S304",     # flake8-bandit suspicious-insecure-cipher-usage
+  "S311",     # flake8-bandit suspicious-non-cryptographic-random-usage
+  "S312",     # flake8-bandit suspicious-telnet-usage
+  "S501",     # request-with-no-cert-validation
+  "S602",     # flake8-bandit subprocess-popen-with-shell-equals-true
+  "S603",     # flake8-bandit subprocess-without-shell-equals-true
+  "SLOT000",  # subclasses of `str` should define `__slots__`
+  "SIM",      # flake8-simplify
+  "SLF",      # flake8-self
+  "T201",     # flake8-print print
+  "TD003",    # flake8-todos missing-todo-link
+  "TRY003",   # tryceratops
+  "TRY400",   # tryceratops
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.coverage.paths]
+source = ['src', '*/site-packages']
+
+[tool.coverage.run]
+source = ['reliqua']
+branch = true
+parallel = true
+
+[tool.coverage.report]
+show_missing = true
+precision = 2

reliqua-0.0.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

reliqua-0.0.6/src/reliqua/__init__.py

@@ -0,0 +1,27 @@
+"""
+MIT License.
+
+Copyright (c) 2017 Terrence Meiczinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from .app import Application, load_config
+
+__all__ = ["Application", "load_config"]

reliqua-0.0.6/src/reliqua/api.py

@@ -0,0 +1,196 @@
+"""
+MIT License.
+
+Copyright (c) 2017 Terrence Meiczinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+import glob
+import importlib
+import inspect
+import os
+import re
+import sys
+import uuid
+
+import falcon
+from falcon_cors import CORS
+
+from .auth import AuthMiddleware
+from .docs import Docs
+from .media_handlers import JSONHandler, TextHandler, YAMLHandler
+from .openapi import OpenApi
+from .resources.base import Resource
+from .sphinx_parser import SphinxParser
+from .swagger import Swagger
+
+
+class Api(falcon.App):
+    """Add auto route and documentation."""
+
+    def __init__(
+        self,
+        resource_path=None,
+        middleware=None,
+        config=None,
+        resource_attributes=None,
+        info=None,
+        openapi=None,
+        **_kwargs,
+    ):
+        """
+        Create an API instance.
+
+        :param str resource_path:             Path to the resource modules
+        :param list middleware:               Middleware
+        :param dict config:                   API configuration parameters
+        :param dict resource_attributes:      Parameters added as resource attributes
+        :param dict info:                     Application information
+        :param dict openapi:                  OpenAPI configuration options
+
+        :return:                               api instance
+        """
+        info = info or {}
+        openapi = openapi or {}
+
+        openapi_path = openapi["path"]
+        self.url = openapi["api_url"]
+
+        self.openapi = openapi
+        self.info = info
+
+        self.openapi["spec"] = f"{openapi_path}/openapi.json"
+        self.openapi["static"] = f"{openapi_path}/static"
+        self.resources = []
+        self.auth = [x for x in middleware if isinstance(x, AuthMiddleware)]
+        self.config = config or {}
+        self.resource_attributes = resource_attributes or {}
+
+        path = os.path.dirname(sys.modules[__name__].__file__)
+        self.openapi["file_path"] = f"{path}/swagger"
+        self.openapi["spec_url"] = f"{self.url}{self.openapi['spec']}"
+        self.openapi["static_url"] = f"{self.url}{self.openapi['static']}"
+
+        middleware = middleware or []
+        cors = CORS(allow_all_origins=True, allow_all_methods=True, allow_all_headers=True)
+        middleware.append(cors.middleware)
+
+        super().__init__(middleware=middleware)
+
+        if not resource_path:
+            resource_path = path + "/resources"
+
+        self.req_options.auto_parse_form_urlencoded = True
+        self.resource_path = resource_path
+
+        self._add_handlers()
+        self._load_resources()
+        self._parse_docstrings()
+        self._add_routes()
+        self._add_docs()
+
+    def _add_handlers(self):
+        extra_handlers = {
+            "application/yaml": YAMLHandler(),
+            "text/html; charset=utf-8": TextHandler(),
+            "text/plain; charset=utf-8": TextHandler(),
+            "application/json": JSONHandler(),
+        }
+
+        self.req_options.media_handlers.update(extra_handlers)
+        self.resp_options.media_handlers.update(extra_handlers)
+
+    def _load_resources(self):
+        resources = []
+        path = f"{self.resource_path}/*.py"
+        print(f"searching {path}")
+        files = glob.glob(path)
+
+        for file in files:
+            print(f"loading {file}")
+            classes = self._get_classes(file)
+            resources.extend(classes)
+
+        # add config to resource
+        self.resources = [x(app_config=self.config, **self.resource_attributes) for x in resources]
+
+    def _is_route_method(self, name, suffix):
+        if not name.startswith("on_"):
+            return None
+
+        if suffix:
+            return name.endswith(suffix)
+
+        return re.search(r"^on_([a-z]+)$", name)
+
+    def _parse_methods(self, resource, route, methods):
+        parser = SphinxParser()
+        for name in methods:
+            operation_id = f"{resource.__class__.__name__}.{name}"
+            action = re.search(r"on_(delete|get|patch|post|put)", name).group(1)
+            method = getattr(resource, name)
+            resource.__data__[route][action] = parser.parse(method, operation_id=operation_id)
+
+    def _parse_resource(self, resource):
+        for route, data in resource.__routes__.items():
+            resource.__data__[route] = {}
+            suffix = data.get("suffix", None)
+            methods = [x for x in dir(resource) if self._is_route_method(x, suffix)]
+            self._parse_methods(resource, route, methods)
+
+    def _parse_docstrings(self):
+        for resource in self.resources:
+            resource.__data__ = {}
+            self._parse_resource(resource)
+
+    def _get_classes(self, filename):
+        classes = []
+        module_name = str(uuid.uuid3(uuid.NAMESPACE_OID, filename))
+        spec = importlib.util.spec_from_file_location(module_name, filename)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        for _, c in inspect.getmembers(module, inspect.isclass):
+            if issubclass(c, Resource) and hasattr(c, "__routes__"):
+                classes.append(c)
+
+        return classes
+
+    def _add_routes(self):
+        for resource in self.resources:
+            routes = resource.__routes__
+            for route, kwargs in routes.items():
+                self.add_route(route, resource, **kwargs)
+
+    def _add_docs(self):
+        swagger = Swagger(
+            self.openapi["static_url"],
+            self.openapi["spec_url"],
+            sort=self.openapi["sort"],
+            highlight=self.openapi["highlight"],
+        )
+        openapi = OpenApi(**self.info, auth=self.auth)
+        openapi.process_resources(self.resources)
+        schema = openapi.schema()
+        print(f"adding static route {self.openapi['docs_endpoint']} {self.openapi['file_path']}")
+        self.add_static_route(self.openapi["static"], self.openapi["file_path"])
+        self.add_route(self.openapi["docs_endpoint"], swagger)
+        print(f"adding openapi file {self.openapi['spec']}")
+        self.add_route(self.openapi["spec"], Docs(schema))