{"id":15013053,"url":"https://github.com/upsight/doctor","last_synced_at":"2025-04-12T04:20:37.147Z","repository":{"id":57423405,"uuid":"81979405","full_name":"upsight/doctor","owner":"upsight","description":"A module using python types to validate request/response data and generate API documentation in Flask Python APIs.","archived":false,"fork":false,"pushed_at":"2020-10-22T15:50:09.000Z","size":442,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-27T10:38:07.434Z","etag":null,"topics":["documentation","json","jsonschema","python","sphinx","validation"],"latest_commit_sha":null,"homepage":"https://doctor.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/upsight.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-14T19:08:14.000Z","updated_at":"2021-09-29T12:27:46.000Z","dependencies_parsed_at":"2022-09-07T04:52:09.417Z","dependency_job_id":null,"html_url":"https://github.com/upsight/doctor","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/upsight%2Fdoctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/upsight%2Fdoctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/upsight%2Fdoctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/upsight%2Fdoctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/upsight","download_url":"https://codeload.github.com/upsight/doctor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248514390,"owners_count":21116952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","json","jsonschema","python","sphinx","validation"],"created_at":"2024-09-24T19:43:39.988Z","updated_at":"2025-04-12T04:20:37.126Z","avatar_url":"https://github.com/upsight.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"doctor\n======\n|docs| |build| |pypi|\n\nThis module uses python types to validate request and response data in\nFlask Python APIs.  It uses `python 3 type hints \u003chttps://docs.python.org/3/library/typing.html\u003e`_\nto validate request paramters and generate API documentation. It also supports\ngeneric schema validation for plain dictionaries. An example of the generated\nAPI documentation can\nbe `found in the docs \u003chttp://doctor.readthedocs.io/en/latest/flask.html#example-api-documentation\u003e`_.\n\nInstall\n-------\n\ndoctor can easily be installed using pip:\n\n    $ pip install doctor\n   \nQuick Start\n-----------\n\nDefine some types that will be used to validate your request parameters.\n\n.. code-block:: python\n\n    # mytypes.py\n    from doctor import types\n\n    # doctor provides helper functions to easily define simple types.\n    FooId = types.integer('The foo ID.')\n    FetchBars = types.boolean('A flag that indicates if we should fetch bars')\n\n    # You can also inherit from type classes to create more complex types.\n    class Foo(types.Object):\n        description = 'A Foo object'\n        example = {'foo_id': 1}\n        properties = {'foo_id': FooId}\n        required = ['foo_id']\n        additional_properties = False\n\nDefine the logic function that our endpoint will route to:\n\n.. code-block:: python\n\n    # foo.py\n    from mytypes import Foo, FooId, FetchBars\n\n    # Note the type annotations on this function definition. This tells Doctor how\n    # to parse and validate parameters for routes attached to this logic function.\n    # The return type annotation will validate the response conforms to an\n    # expected definition in development environments.  In non-development\n    # environments a warning will be logged.\n    def get_foo(foo_id: FooId, fetch_bars: FetchBars=False) -\u003e Foo:\n        \"\"\"Fetches the Foo object and optionally related bars.\"\"\"\n        return Foo.get_by_id(foo_id, fetch_bars=fetch_bars)\n        \nNow tie the endpoint to the logic function with a route:\n\n.. code-block:: python\n\n    from flask import Flask\n    from flask_restful import Api\n    from doctor.routing import create_routes, get, Route\n\n    from foo import get_foo\n   \n    routes = (\n        Route('/foo/\u003cint:foo_id\u003e/', methods=(\n            get(get_foo),)\n        ),\n    )\n    \n    app = Flask(__name__)\n    api = Api(app)\n    for route, resource in create_routes(routes):\n        api.add_resource(resource, route)\n    \nThat's it, you now have a functioning API endpoint you can curl and the request is automatically validated for you based on your\nschema.  Positional arguments in your logic function are considered required request parameters and keyword arguments are considered\noptional.  As a bonus, using the `autoflask \u003chttp://doctor.readthedocs.io/en/latest/docs.html\u003e`_ sphinx directive, you will also get\nautomatically generated API documentation.\n\n.. image:: example_api_docs.png\n    :alt: Generated API documentation\n    :align: left\n    :target: http://doctor.readthedocs.io/en/latest/docs.html\n   \nDocumentation\n-------------\n\nDocumentation and a full example is available at readthedocs_.\n   \nRunning Tests\n-------------\n\nTests can be run with tox_. It will handle installing dependencies into a\nvirtualenv, running tests, and rebuilding documentation.\n\nThen run Tox:\n\n.. code-block:: bash\n\n    cd doctor\n    tox\n\n\nYou can pass arguments to pytest directly:\n\n.. code-block:: bash\n\n    tox -- test/test_flask.py\n\n\n.. _readthedocs: http://doctor.readthedocs.io/en/latest/index.html\n.. _tox: https://testrun.org/tox/latest/\n\n.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest\n    :alt: Documentation Status\n    :scale: 100%\n    :target: http://doctor.readthedocs.io/en/latest/index.html\n    \n.. |build| image:: https://api.travis-ci.org/upsight/doctor.svg?branch=master\n    :alt: Build Status\n    :scale: 100%\n    :target: https://travis-ci.org/upsight/doctor\n    \n.. |pypi| image:: https://img.shields.io/pypi/v/doctor.svg\n    :alt: Pypi\n    :scale: 100%\n    :target: https://pypi.python.org/pypi/doctor/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fupsight%2Fdoctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fupsight%2Fdoctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fupsight%2Fdoctor/lists"}