bareASGI-rest 5.0.0__tar.gz

bareasgi_rest-5.0.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: bareASGI-rest
+Version: 5.0.0
+Summary: REST support for bareASGI
+Author-email: Rob Blackbourn <rob.blackbourn@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://bareASGI.github.io/bareASGI-rest
+Project-URL: Repository, https://github.com/bareASGI/bareASGI-rest
+Project-URL: Issues, https://github.com/bareASGI/bareASGI-rest/issues
+Keywords: asgi,web,framework,asyncio,http
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: bareUtils<6,>=5.1.0
+Requires-Dist: bareASGI<6,>=5.0.0
+Requires-Dist: bareASGI-jinja2<6,>=5.0.0
+Requires-Dist: docstring-parser<1,>=0.15
+Requires-Dist: lxml<6,>=5.4
+Requires-Dist: stringcase<2,>=1.2
+Requires-Dist: jetblack-serialization<5,>=4.0.13
+Requires-Dist: typing-extensions<5,>=4
+Requires-Dist: typing_inspect<1,>=0.9
+Provides-Extra: dev
+Requires-Dist: autopep8; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: jetblack-markdown; extra == "docs"
+Requires-Dist: mike; extra == "docs"
+Provides-Extra: examples
+Requires-Dist: hypercorn; extra == "examples"
+Requires-Dist: uvicorn; extra == "examples"
+
+# bareASGI-rest
+
+This package provides enhanced support for writing REST
+APIs with [bareASGI](https://bareasgi.com),
+(read the [docs](https://bareASGI.github.io/bareASGI-rest/)).
+
+It includes:
+
+- A router to simplify the creation of REST APIs,
+- A swagger API endpoint
+
+This is a Python 3.8+ package.
+
+## Installation
+
+The package can be installed from pypi.
+
+```bash
+$ pip install bareASGI-rest
+```
+
+An ASGI server will be required to run the code. The examples below use
+[uvicorn](https://www.uvicorn.org/).
+
+```bash
+$ pip install uvicorn
+```
+
+## Usage
+
+The router provided by this package maps the arguments and
+types of request handlers.
+
+We will create a mock book repository.
+
+### Creating typed dictionaries
+
+Here is the type of a book. We use `TypedDict` to allow automatic type discovery
+
+```python
+from datetime import datetime
+from typing import TypedDict
+
+
+class Book(TypedDict):
+    """A Book
+
+    Args:
+        book_id (int): The book id
+        title (str): The title
+        author (str): The author
+        published (datetime): The publication date
+    """
+    book_id: int
+    title: str
+    author: str
+    published: datetime
+```
+
+Note: the docstring will be used to provide documentation for swagger.
+
+### Creating the API
+
+Now we can build the API.
+
+```python
+from datetime import datetime
+
+from bareasgi_rest import RestError
+
+
+BOOKS: dict[int, Book] = {}
+NEXT_ID: int = 0
+
+async def get_books() -> list[Book]:
+    """Get all the books.
+
+    This method gets all the books in the shop.
+
+    Returns:
+        list[Book]: All the books
+    """
+    return list(BOOKS.values())
+
+
+async def get_book(book_id: int) -> Book:
+    """Get a book for a given id
+
+    Args:
+        book_id (int): The id of the book
+
+    Raises:
+        RestError: 404, when a book is not found
+
+    Returns:
+        Book: The book
+    """
+
+    if book_id not in BOOKS:
+        raise RestError(404, "Book not found")
+
+    return BOOKS[book_id]
+
+
+async def create_book(
+        author: str,
+        title: str,
+        published: datetime
+) -> int:
+    """Add a book
+
+    Args:
+        author (str): The author
+        title (str): The title
+        published (datetime): The publication date
+
+    Returns:
+        int: The id of the new book
+    """
+    NEXT_ID += 1
+    BOOKS[NEXT_ID] = Book(
+        book_id=NEXT_ID,
+        title=title,
+        author=author,
+        published=published
+    )
+    return NEXT_ID
+
+
+async def update_book(
+        book_id: int,
+        author: str,
+        title: str,
+        published: datetime
+) -> None:
+    """Update a book
+
+    Args:
+        book_id (int): The id of the book to update
+        author (str): The new author
+        title (str): The title
+        published (datetime): The publication date
+
+    Raises:
+        RestError: 404, when a book is not found
+    """
+    if book_id not in BOOKS:
+        raise RestError(404, "Book not found")
+    BOOKS[book_id]['title'] = title
+    BOOKS[book_id]['author'] = author
+    BOOKS[book_id]['published'] = published
+```
+
+We can see that errors are handler by raising ResetError.
+A convention has been applied such that the status code MUST
+appear before the message, separated by a comma.
+
+### Adding support for the REST router
+
+Now we must create our application and add support for the router.
+
+```python
+from bareasgi import Application
+from bareasgi_rest import RestHttpRouter, add_swagger_ui
+
+
+router = RestHttpRouter(
+    None,
+    title="Books",
+    version="1",
+    description="A book api",
+    base_path='/api/1',
+    tags=[
+        {
+            'name': 'Books',
+            'description': 'The book store API'
+        }
+    ]
+)
+app = Application(http_router=router)
+add_swagger_ui(app)
+```
+
+Note the `base_path` argument can be used to prefix all
+paths.
+
+The `RestHttpRouter` is a subclass of the basic router, so
+all those methods are also available.
+
+### Creating the routes
+
+Now we can create the routes:
+
+```python
+tags = ['Books']
+router.add_rest({'GET'}, '/books', get_books,tags=tags)
+router.add_rest({'GET'}, '/books/{bookId:int}', get_book, tags=tags)
+router.add_rest({'POST'}, '/books', create_book, tags=tags, status_code=201)
+router.add_rest({'PUT'}, '/books/{bookId:int}', update_book, tags=tags, status_code=204)
+```
+
+First we should note that the paths will be prefixed with the
+`base_path` provided to the router.
+
+Referring back to the implementation of `get_book` we can
+see that the camel-case path variable `bookId` has been
+mapped to the snake-case `book_id` parameter. The JSON object provided in the body of the `create_book` will
+similarly map camel-cased properties to the snake-cased
+function parameters.
+
+We can also see how the status codes have been overridden
+for the `POST` and `PUT` endpoints, and all the routes
+have the "Books" tag for grouping in the UI.
+
+### Serving the API
+
+Finally we can serve the API:
+
+```python
+import uvicorn
+
+uvicorn.run(app, port=9009)
+```
+
+Browsing to http://localhost/api/1/swagger we should see:
+
+![Top Level](screenshot1.png)
+
+When we expand `GET /books/{bookId}` we can see all the
+information provided in the docstring and typing has been
+passed through to the swagger UI.
+
+![GET /books/{bookId}](screenshot2.png)
+
+## Thanks
+
+Thanks to [rr-](https://github.com/rr-) and contributors
+for the excellent
+[docstring-parser](https://github.com/rr-/docstring_parser)
+package.

bareasgi_rest-5.0.0/README.md

@@ -0,0 +1,240 @@
+# bareASGI-rest
+
+This package provides enhanced support for writing REST
+APIs with [bareASGI](https://bareasgi.com),
+(read the [docs](https://bareASGI.github.io/bareASGI-rest/)).
+
+It includes:
+
+- A router to simplify the creation of REST APIs,
+- A swagger API endpoint
+
+This is a Python 3.8+ package.
+
+## Installation
+
+The package can be installed from pypi.
+
+```bash
+$ pip install bareASGI-rest
+```
+
+An ASGI server will be required to run the code. The examples below use
+[uvicorn](https://www.uvicorn.org/).
+
+```bash
+$ pip install uvicorn
+```
+
+## Usage
+
+The router provided by this package maps the arguments and
+types of request handlers.
+
+We will create a mock book repository.
+
+### Creating typed dictionaries
+
+Here is the type of a book. We use `TypedDict` to allow automatic type discovery
+
+```python
+from datetime import datetime
+from typing import TypedDict
+
+
+class Book(TypedDict):
+    """A Book
+
+    Args:
+        book_id (int): The book id
+        title (str): The title
+        author (str): The author
+        published (datetime): The publication date
+    """
+    book_id: int
+    title: str
+    author: str
+    published: datetime
+```
+
+Note: the docstring will be used to provide documentation for swagger.
+
+### Creating the API
+
+Now we can build the API.
+
+```python
+from datetime import datetime
+
+from bareasgi_rest import RestError
+
+
+BOOKS: dict[int, Book] = {}
+NEXT_ID: int = 0
+
+async def get_books() -> list[Book]:
+    """Get all the books.
+
+    This method gets all the books in the shop.
+
+    Returns:
+        list[Book]: All the books
+    """
+    return list(BOOKS.values())
+
+
+async def get_book(book_id: int) -> Book:
+    """Get a book for a given id
+
+    Args:
+        book_id (int): The id of the book
+
+    Raises:
+        RestError: 404, when a book is not found
+
+    Returns:
+        Book: The book
+    """
+
+    if book_id not in BOOKS:
+        raise RestError(404, "Book not found")
+
+    return BOOKS[book_id]
+
+
+async def create_book(
+        author: str,
+        title: str,
+        published: datetime
+) -> int:
+    """Add a book
+
+    Args:
+        author (str): The author
+        title (str): The title
+        published (datetime): The publication date
+
+    Returns:
+        int: The id of the new book
+    """
+    NEXT_ID += 1
+    BOOKS[NEXT_ID] = Book(
+        book_id=NEXT_ID,
+        title=title,
+        author=author,
+        published=published
+    )
+    return NEXT_ID
+
+
+async def update_book(
+        book_id: int,
+        author: str,
+        title: str,
+        published: datetime
+) -> None:
+    """Update a book
+
+    Args:
+        book_id (int): The id of the book to update
+        author (str): The new author
+        title (str): The title
+        published (datetime): The publication date
+
+    Raises:
+        RestError: 404, when a book is not found
+    """
+    if book_id not in BOOKS:
+        raise RestError(404, "Book not found")
+    BOOKS[book_id]['title'] = title
+    BOOKS[book_id]['author'] = author
+    BOOKS[book_id]['published'] = published
+```
+
+We can see that errors are handler by raising ResetError.
+A convention has been applied such that the status code MUST
+appear before the message, separated by a comma.
+
+### Adding support for the REST router
+
+Now we must create our application and add support for the router.
+
+```python
+from bareasgi import Application
+from bareasgi_rest import RestHttpRouter, add_swagger_ui
+
+
+router = RestHttpRouter(
+    None,
+    title="Books",
+    version="1",
+    description="A book api",
+    base_path='/api/1',
+    tags=[
+        {
+            'name': 'Books',
+            'description': 'The book store API'
+        }
+    ]
+)
+app = Application(http_router=router)
+add_swagger_ui(app)
+```
+
+Note the `base_path` argument can be used to prefix all
+paths.
+
+The `RestHttpRouter` is a subclass of the basic router, so
+all those methods are also available.
+
+### Creating the routes
+
+Now we can create the routes:
+
+```python
+tags = ['Books']
+router.add_rest({'GET'}, '/books', get_books,tags=tags)
+router.add_rest({'GET'}, '/books/{bookId:int}', get_book, tags=tags)
+router.add_rest({'POST'}, '/books', create_book, tags=tags, status_code=201)
+router.add_rest({'PUT'}, '/books/{bookId:int}', update_book, tags=tags, status_code=204)
+```
+
+First we should note that the paths will be prefixed with the
+`base_path` provided to the router.
+
+Referring back to the implementation of `get_book` we can
+see that the camel-case path variable `bookId` has been
+mapped to the snake-case `book_id` parameter. The JSON object provided in the body of the `create_book` will
+similarly map camel-cased properties to the snake-cased
+function parameters.
+
+We can also see how the status codes have been overridden
+for the `POST` and `PUT` endpoints, and all the routes
+have the "Books" tag for grouping in the UI.
+
+### Serving the API
+
+Finally we can serve the API:
+
+```python
+import uvicorn
+
+uvicorn.run(app, port=9009)
+```
+
+Browsing to http://localhost/api/1/swagger we should see:
+
+![Top Level](screenshot1.png)
+
+When we expand `GET /books/{bookId}` we can see all the
+information provided in the docstring and typing has been
+passed through to the swagger UI.
+
+![GET /books/{bookId}](screenshot2.png)
+
+## Thanks
+
+Thanks to [rr-](https://github.com/rr-) and contributors
+for the excellent
+[docstring-parser](https://github.com/rr-/docstring_parser)
+package.

bareasgi_rest-5.0.0/pyproject.toml

@@ -0,0 +1,114 @@
+[project]
+name = "bareASGI-rest"
+version = "5.0.0"
+description = "REST support for bareASGI"
+authors = [
+    { name = "Rob Blackbourn", email = "rob.blackbourn@gmail.com" }
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+]
+readme = "README.md"
+dependencies = [
+    "bareUtils>=5.1.0,<6",
+    "bareASGI >=5.0.0,<6",
+    "bareASGI-jinja2>=5.0.0,<6",
+    "docstring-parser>=0.15,<1",
+    "lxml>=5.4,<6",
+    "stringcase>=1.2,<2",
+    "jetblack-serialization>=4.0.13,<5",
+    "typing-extensions>=4,<5",
+    "typing_inspect>=0.9,<1"
+]
+license = "Apache-2.0"
+license-files = [
+    "LICENSE"
+]
+keywords = [
+    "asgi",
+    "web",
+    "framework",
+    "asyncio",
+    "http",
+]
+
+[project.optional-dependencies]
+dev = [
+    "autopep8",
+    "coverage",
+    "mypy",
+    "pytest",
+    "pytest-asyncio",
+    "pylint",
+    "types-setuptools",
+]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "jetblack-markdown",
+    "mike",
+]
+examples = [
+    "hypercorn",
+    "uvicorn"
+]
+
+[project.urls]
+Homepage = "https://bareASGI.github.io/bareASGI-rest"
+Repository = "https://github.com/bareASGI/bareASGI-rest"
+Issues = "https://github.com/bareASGI/bareASGI-rest/issues"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+# pylint
+[tool.pylint.main]
+py-version = "3.12"
+jobs = 4
+
+[tool.pylint.basic]
+good-names = ["i", "j", "k", "ex", "Run", "_"]
+bad-names = ["foo", "bar", "baz", "toto", "tutu", "tata"]
+
+[tool.pylint."messages control"]
+disable = [
+    "raw-checker-failed",
+    "bad-inline-option",
+    "locally-disabled",
+    "file-ignored",
+    "suppressed-message",
+    "useless-suppression",
+    "deprecated-pragma",
+    "use-symbolic-message-instead",
+    "missing-module-docstring",
+]
+
+# pytest
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "function"
+
+# mypy
+[tool.mypy]
+files = [ "src", "tests", "demos" ]
+
+[[tool.mypy.overrides]]
+module = "pytest"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "stringcase"
+ignore_missing_imports = true

bareasgi_rest-5.0.0/setup.cfg

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