diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-automd.spec | 454 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 456 insertions, 0 deletions
@@ -0,0 +1 @@ +/AutoMD-1.10.0.tar.gz diff --git a/python-automd.spec b/python-automd.spec new file mode 100644 index 0000000..c3a300d --- /dev/null +++ b/python-automd.spec @@ -0,0 +1,454 @@ +%global _empty_manifest_terminate_build 0 +Name: python-AutoMD +Version: 1.10.0 +Release: 1 +Summary: AutoMD is a documentation library for Flask APIs build with FlaskRESTful and Webargs. +License: MIT +URL: https://github.com/cliftbar/automd +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/8e/10/23cae9b2ae9c5b05ed414bfe9d8135ab3f40f6712ee73e97f362cf5f6c5c/AutoMD-1.10.0.tar.gz +BuildArch: noarch + +Requires: python3-flask +Requires: python3-flask-restful +Requires: python3-webargs +Requires: python3-apispec +Requires: python3-pyyaml +Requires: python3-marshmallow +Requires: python3-werkzeug + +%description +# AutoMD +AutoMD is a documentation library for Flask APIs build with FlaskRESTful and Webargs. +Endpoint parameters and basic responses are automatically parsed into the OpenAPI specification, +using Type Hints and introspection, and a endpoints registered to serve the specification. + +## Motivation +Documentation libraries tend to rely heavily on elaborate docstrings and static generation from source code. +This library requires minimal changes to existing code, and most information (especially parameter specs) +doesn't rely on keeping docstrings up to date. + +## Installation +AutoMD is available through PyPi. AutoMD requires Python >= 3.6 (f-strings are too convenient to ignore) +Install using pip: +``` +pip install automd +``` + +AutoMD also install the following dependencies: +- flask +- flask-restful +- webargs +- apispec +- pyyaml +- marshmallow +- werkzeug + +## Usage +### AutoMD registration/initialization +The first step is to initialize the AutoMD app from a FlaskRESTful Api. + +```python +from flask import Flask +from flask_restful import Api +from automd.registration import AutoMDApp + + +app: Flask = Flask(__name__) +api: Api = Api(app) + +spec: AutoMDApp = AutoMDApp(api, title="AutoMD Test App", app_version="1.0.0", openapi_version="3.0.0") +``` + +After that, all that is *required* is adding the `@automd` decorator to an existing Resource endpoint. + +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd + + +class MinimalStatus(Resource): + get_query_arguments = { + "text": fields.String(required=False) + } + + @automd() + @use_kwargs(get_query_arguments) + def get(self, text): + return text +``` +which will mark the endpoint for inclusion in the OpenAPI spec. In this example, the spec information +will be pretty limited, but will still have the API url, argument, and a default value. + +With more complete python annotations, more information can be gleaned: +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd + + +class IntrospectionStatus(Resource): + post_query_arguments = { + "text": fields.String(required=False) + } + + @automd() + @use_kwargs(post_query_arguments, location="json") + def post(self, text: str = "Hello AutoMD") -> str: + ret_text: str = "status check OK" + + if text is not None: + ret_text = f"{ret_text}: {text}" + + return ret_text +``` +From this the APISpec also get the parameter type, default value, and API response type. It does not get the parameter +location yet though, that takes more aguements to automd. + +Filling in more information in the webargs fields, automd decorator, use_kwargs decorator, and using one of the +AutoMD response classes for type annotation and gives even better information: +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd +from automd.responses import ValueResponse + +class Status(Resource): + get_query_arguments = { + "text": fields.String(required=False, description='Text to return', doc_default="Hello AutoMD") + } + + @automd(parameter_schema=get_query_arguments, + summary="Status Endpoint", + description="Status Endpoint, responds with a message made from the input string") + @use_kwargs(get_query_arguments, location="query") + def get(self, text: str = None) -> ValueResponse: + log_text: str = "status check OK" + + log_text = f"{log_text}: {text or 'Hello AutoMD'}" + + return ValueResponse(log_text) +``` + +With this information, argument types, return types, summaries, descriptions, detailed default +information, and parameter location info (body, query, etc) is included. Summary and description +are the only "magic strings" needed, and those will generally not change much or be onerous to +keep up to date compared to the automatically grabbed information. + +An example Flask API app is provided to showcase some functionality. Start it using `run.py`. +A sample of the OpenAPI spec generated is [here](https://cliftbar.github.io/automd/documentation/sample_spec.html). + + + + +%package -n python3-AutoMD +Summary: AutoMD is a documentation library for Flask APIs build with FlaskRESTful and Webargs. +Provides: python-AutoMD +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-AutoMD +# AutoMD +AutoMD is a documentation library for Flask APIs build with FlaskRESTful and Webargs. +Endpoint parameters and basic responses are automatically parsed into the OpenAPI specification, +using Type Hints and introspection, and a endpoints registered to serve the specification. + +## Motivation +Documentation libraries tend to rely heavily on elaborate docstrings and static generation from source code. +This library requires minimal changes to existing code, and most information (especially parameter specs) +doesn't rely on keeping docstrings up to date. + +## Installation +AutoMD is available through PyPi. AutoMD requires Python >= 3.6 (f-strings are too convenient to ignore) +Install using pip: +``` +pip install automd +``` + +AutoMD also install the following dependencies: +- flask +- flask-restful +- webargs +- apispec +- pyyaml +- marshmallow +- werkzeug + +## Usage +### AutoMD registration/initialization +The first step is to initialize the AutoMD app from a FlaskRESTful Api. + +```python +from flask import Flask +from flask_restful import Api +from automd.registration import AutoMDApp + + +app: Flask = Flask(__name__) +api: Api = Api(app) + +spec: AutoMDApp = AutoMDApp(api, title="AutoMD Test App", app_version="1.0.0", openapi_version="3.0.0") +``` + +After that, all that is *required* is adding the `@automd` decorator to an existing Resource endpoint. + +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd + + +class MinimalStatus(Resource): + get_query_arguments = { + "text": fields.String(required=False) + } + + @automd() + @use_kwargs(get_query_arguments) + def get(self, text): + return text +``` +which will mark the endpoint for inclusion in the OpenAPI spec. In this example, the spec information +will be pretty limited, but will still have the API url, argument, and a default value. + +With more complete python annotations, more information can be gleaned: +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd + + +class IntrospectionStatus(Resource): + post_query_arguments = { + "text": fields.String(required=False) + } + + @automd() + @use_kwargs(post_query_arguments, location="json") + def post(self, text: str = "Hello AutoMD") -> str: + ret_text: str = "status check OK" + + if text is not None: + ret_text = f"{ret_text}: {text}" + + return ret_text +``` +From this the APISpec also get the parameter type, default value, and API response type. It does not get the parameter +location yet though, that takes more aguements to automd. + +Filling in more information in the webargs fields, automd decorator, use_kwargs decorator, and using one of the +AutoMD response classes for type annotation and gives even better information: +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd +from automd.responses import ValueResponse + +class Status(Resource): + get_query_arguments = { + "text": fields.String(required=False, description='Text to return', doc_default="Hello AutoMD") + } + + @automd(parameter_schema=get_query_arguments, + summary="Status Endpoint", + description="Status Endpoint, responds with a message made from the input string") + @use_kwargs(get_query_arguments, location="query") + def get(self, text: str = None) -> ValueResponse: + log_text: str = "status check OK" + + log_text = f"{log_text}: {text or 'Hello AutoMD'}" + + return ValueResponse(log_text) +``` + +With this information, argument types, return types, summaries, descriptions, detailed default +information, and parameter location info (body, query, etc) is included. Summary and description +are the only "magic strings" needed, and those will generally not change much or be onerous to +keep up to date compared to the automatically grabbed information. + +An example Flask API app is provided to showcase some functionality. Start it using `run.py`. +A sample of the OpenAPI spec generated is [here](https://cliftbar.github.io/automd/documentation/sample_spec.html). + + + + +%package help +Summary: Development documents and examples for AutoMD +Provides: python3-AutoMD-doc +%description help +# AutoMD +AutoMD is a documentation library for Flask APIs build with FlaskRESTful and Webargs. +Endpoint parameters and basic responses are automatically parsed into the OpenAPI specification, +using Type Hints and introspection, and a endpoints registered to serve the specification. + +## Motivation +Documentation libraries tend to rely heavily on elaborate docstrings and static generation from source code. +This library requires minimal changes to existing code, and most information (especially parameter specs) +doesn't rely on keeping docstrings up to date. + +## Installation +AutoMD is available through PyPi. AutoMD requires Python >= 3.6 (f-strings are too convenient to ignore) +Install using pip: +``` +pip install automd +``` + +AutoMD also install the following dependencies: +- flask +- flask-restful +- webargs +- apispec +- pyyaml +- marshmallow +- werkzeug + +## Usage +### AutoMD registration/initialization +The first step is to initialize the AutoMD app from a FlaskRESTful Api. + +```python +from flask import Flask +from flask_restful import Api +from automd.registration import AutoMDApp + + +app: Flask = Flask(__name__) +api: Api = Api(app) + +spec: AutoMDApp = AutoMDApp(api, title="AutoMD Test App", app_version="1.0.0", openapi_version="3.0.0") +``` + +After that, all that is *required* is adding the `@automd` decorator to an existing Resource endpoint. + +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd + + +class MinimalStatus(Resource): + get_query_arguments = { + "text": fields.String(required=False) + } + + @automd() + @use_kwargs(get_query_arguments) + def get(self, text): + return text +``` +which will mark the endpoint for inclusion in the OpenAPI spec. In this example, the spec information +will be pretty limited, but will still have the API url, argument, and a default value. + +With more complete python annotations, more information can be gleaned: +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd + + +class IntrospectionStatus(Resource): + post_query_arguments = { + "text": fields.String(required=False) + } + + @automd() + @use_kwargs(post_query_arguments, location="json") + def post(self, text: str = "Hello AutoMD") -> str: + ret_text: str = "status check OK" + + if text is not None: + ret_text = f"{ret_text}: {text}" + + return ret_text +``` +From this the APISpec also get the parameter type, default value, and API response type. It does not get the parameter +location yet though, that takes more aguements to automd. + +Filling in more information in the webargs fields, automd decorator, use_kwargs decorator, and using one of the +AutoMD response classes for type annotation and gives even better information: +```python +from flask_restful import Resource +from marshmallow import fields +from webargs.flaskparser import use_kwargs +from automd.decorators import automd +from automd.responses import ValueResponse + +class Status(Resource): + get_query_arguments = { + "text": fields.String(required=False, description='Text to return', doc_default="Hello AutoMD") + } + + @automd(parameter_schema=get_query_arguments, + summary="Status Endpoint", + description="Status Endpoint, responds with a message made from the input string") + @use_kwargs(get_query_arguments, location="query") + def get(self, text: str = None) -> ValueResponse: + log_text: str = "status check OK" + + log_text = f"{log_text}: {text or 'Hello AutoMD'}" + + return ValueResponse(log_text) +``` + +With this information, argument types, return types, summaries, descriptions, detailed default +information, and parameter location info (body, query, etc) is included. Summary and description +are the only "magic strings" needed, and those will generally not change much or be onerous to +keep up to date compared to the automatically grabbed information. + +An example Flask API app is provided to showcase some functionality. Start it using `run.py`. +A sample of the OpenAPI spec generated is [here](https://cliftbar.github.io/automd/documentation/sample_spec.html). + + + + +%prep +%autosetup -n AutoMD-1.10.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-AutoMD -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Thu May 18 2023 Python_Bot <Python_Bot@openeuler.org> - 1.10.0-1 +- Package Spec generated @@ -0,0 +1 @@ +a58ce927d150a1555505da85f2c93237 AutoMD-1.10.0.tar.gz |