richapi 0.1.0__tar.gz

richapi-0.1.0/.envrc

@@ -0,0 +1,4 @@
+VIRTUAL_ENV="$(pwd)/.venv"
+PATH=$VIRTUAL_ENV/bin:$PATH
+export VIRTUAL_ENV
+export PATH

richapi-0.1.0/.github/workflows/deploy-docs-on-demand.yml

@@ -0,0 +1,24 @@
+name: Deploy Docs On Demand
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy-docs-on-demand:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: yezz123/setup-uv@v4
+
+      - name: Setup python ${{ matrix.python-version }} and uv
+        shell: bash
+        run: |
+          uv sync --frozen
+
+      - name: Deploy documentation
+        run: uv run python deploy_docs.py

richapi-0.1.0/.github/workflows/main.yml

@@ -0,0 +1,41 @@
+name: Main
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  tox:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: yezz123/setup-uv@v4
+
+      - name: Pin python-version ${{ matrix.python-version }}
+        run: uv python pin ${{ matrix.python-version }}
+
+      - name: Setup python ${{ matrix.python-version }} and uv
+        shell: bash
+        run: |
+          uv sync --frozen
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Run tests
+        run: make test
+
+      - name: Run check
+        run: make check

richapi-0.1.0/.github/workflows/on-release-main.yml

@@ -0,0 +1,40 @@
+name: release-main
+
+on:
+  release:
+    types: [published]
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v3
+
+      - name: Export tag
+        id: vars
+        run: echo tag=${GITHUB_REF#refs/*/} >> $GITHUB_OUTPUT
+
+      - name: Set up python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: yezz123/setup-uv@v4
+
+      - name: Setup python ${{ matrix.python-version }} and uv
+        shell: bash
+        run: |
+          uv sync --frozen
+
+      - name: Install the latest version of rye
+        uses: eifinger/setup-rye@v4
+
+      - name: Build and publish
+        run: |
+          rye build
+          rye publish --token $PYPI_TOKEN --yes
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+          RELEASE_VERSION: ${{ steps.vars.outputs.tag }}

richapi-0.1.0/.gitignore

@@ -0,0 +1,168 @@
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.DS_Store
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Vscode config files
+.vscode/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

richapi-0.1.0/.python-version

@@ -0,0 +1 @@
+3.9.19

richapi-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.3
+Name: richapi
+Version: 0.1.0
+Summary: Find HTTPExceptions and turn them into documented responses!
+Project-URL: repository, https://github.com/ManiMozaffar/richapi
+Project-URL: Homepage, https://github.com/ManiMozaffar/richapi
+Project-URL: Documentation, https://github.com/ManiMozaffar/richapi
+Project-URL: Source, https://github.com/ManiMozaffar/richapi
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: loguru>=0.7.2
+Requires-Dist: typer>=0.12.5
+Description-Content-Type: text/markdown
+
+### Installation
+
+To install the package, run the following command:
+
+```bash
+pip install richapi
+```
+
+## Help
+
+See [documentation](https://manimozaffar.github.io/richapi/latest/) for more details.
+
+### Use Cases
+
+RichAPI is designed to simplify FastAPI projects by automatically generating documented HTTP responses from HTTPException without extra effort! 🎉
+
+This package is planned to have more features for now that might be essential for any FastAPI project later.
+
+What would you see WITHOUT RichAPI:
+![Screenshot](docs/images/without-richapi.png)
+
+After compiling OpenAPI WITH RichAPI (extended with all possible exceptions coming from your router):
+![Screenshot](docs/images/with-richapi.png)

richapi-0.1.0/README.md

@@ -0,0 +1,23 @@
+### Installation
+
+To install the package, run the following command:
+
+```bash
+pip install richapi
+```
+
+## Help
+
+See [documentation](https://manimozaffar.github.io/richapi/latest/) for more details.
+
+### Use Cases
+
+RichAPI is designed to simplify FastAPI projects by automatically generating documented HTTP responses from HTTPException without extra effort! 🎉
+
+This package is planned to have more features for now that might be essential for any FastAPI project later.
+
+What would you see WITHOUT RichAPI:
+![Screenshot](docs/images/without-richapi.png)
+
+After compiling OpenAPI WITH RichAPI (extended with all possible exceptions coming from your router):
+![Screenshot](docs/images/with-richapi.png)

richapi-0.1.0/deploy_docs.py

@@ -0,0 +1,27 @@
+import logging
+import subprocess
+import sys
+
+from richapi.__version__ import __version__
+
+logger = logging.getLogger(__name__)
+
+
+def run_command(command: str) -> None:
+    try:
+        result = subprocess.run(
+            command, shell=True, check=True, capture_output=True, text=True
+        )
+        print(result.stdout)
+    except subprocess.CalledProcessError:
+        logger.exception("Error executing command")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    command = "mike set-default latest"
+    run_command(command)
+
+    command = f"mike deploy --push --update-aliases {__version__} latest"
+
+    run_command(command)

richapi-0.1.0/docs/advance.md

@@ -0,0 +1,36 @@
+## Advance
+
+This is guideline for how to use the library in more advanced ways.
+
+### Customization of the OpenAPI schema
+
+Sometimes, your exceptions is more than 'details'.
+In that case, you can very explicitly define the exception JSON schema inside the exception class. You may even use Pydantic to define the schema dynamically so you don't need to write the schema manually.
+
+All you need to do, is to return type HTTPExceptionSchema correctly on the method `get_json_schema` of your exception class which you inherited from `BaseHTTPException`.
+
+Imagine you are writing an exception that is returning a user balance and a time to retry again a failed bank transaction, you can define the schema like this:
+
+```python
+from richapi import  BaseHTTPException
+from richapi.exc_parser import HTTPExceptionSchema
+from pydantic import create_model
+
+class YourException(BaseHTTPException):
+    user_balance: int
+    retry_again_in: int
+    status_code: int = 400
+
+    @classmethod
+    def get_json_schema(cls) -> HTTPExceptionSchema:
+        schema = create_model(name, user_balance=(int, ...), retry_again_in=(int, ...))
+        return HTTPExceptionSchema(
+            schema_name="YourException",
+            schema_desc="This is a custom exception",
+            status_code=cls.status_code,
+            response_schema_json=schema.model_json_schema(),
+        )
+
+```
+
+Remember that the responsbility of raising and returning the correct data on FastAPI is not library responsibility, but the responsibility of the developer. The library is only responsible for generating the OpenAPI schema by looking at the functions and classes that are raising exceptions.

richapi-0.1.0/docs/conventions.md

@@ -0,0 +1,72 @@
+## Conventions
+
+This is guideline for how to raise exceptions so that the library can generate the OpenAPI schema from them.
+
+Since the library is a mini compiler using Abstract Syntax Tree and functions global to extract exceptions and their responses, there are some conventions that you need to follow to get the best out of it.
+
+Keep in mind that if you don't follow these conventions, there would be alot false positive and false negative cases, and the library may not be able to extract the exceptions and their responses correctly.
+
+### Inherit from `richapi.BaseHTTPException`
+
+Exceptions are better to be very concrete, without having any dynamic data in them.
+So that using `raise Class` is enough to raise them.
+
+Exceptions ideally should inherit from `richapi.BaseHTTPException`. Check the ideal case below:
+
+```python
+from richapi import BaseHTTPException
+
+class UserNotFound(BaseHTTPException):
+    status_code = 404
+    details = "User not found"
+```
+
+And then, only writing `raise UserNotFound` is enough to raise the exception. This is most ideal case.
+
+### Avoiding dynamic data in the constructor of the exceptions
+
+Exceptions should not have any dynamic data in them.
+For example the code below is NOT ideal:
+
+```python
+
+user_id = 1 # imaginary dynamic data
+error_message = f"User {user_id} is not allowed to perform this action"
+raise FooException(detail=error_message)
+```
+
+Since the library is using static analyzers to extract the exceptions, it is not possible to extract the dynamic data from the exceptions. (or rather very hard to do so)
+
+### Avoiding usage of magic methods
+
+Magic methods are implicit, therefore extracting them from the abstract syntax tree is exteremly hard and equal to rewriting the Python interpreter.
+
+One example that you should not do in your code:
+
+```python
+class Foo:
+    def __init__(self, bar):
+        self.bar = bar
+
+    def __eq__(self, other):
+        raise HTTPException(status_code=400, detail="This is not allowed")
+```
+
+### Keep it simple
+
+The ideal way to raise exceptions is to keep it simple from syntax point of view;
+
+This is very ideal and can be easily parsed and compiled.
+
+```python
+raise HTTPException(status_code=400, detail="This is not allowed")
+```
+
+But the below example MAY not be parsed correctly:
+
+```python
+exc = lambda: HTTPException
+raise exc()(status_code=400, detail="This is not allowed")
+```
+
+Keep it simple, keep the exception type next to raise keyword; without any dynamic data in the constructor. This help the library to extract the exceptions and their responses and guarantee that they are correctly compiled into the OpenAPI schema.

richapi-0.1.0/docs/index.md

@@ -0,0 +1,111 @@
+### Installation
+
+To install the package, run the following command:
+
+```bash
+pip install richapi
+```
+
+### Usage
+
+**RichAPI is designed to simplify FastAPI projects by automatically generating documented HTTP responses from HTTPException without extra effort! 🎉
+**
+This package is planned to have more features for now that might be essential for any FastAPI project later.
+
+There are multiple way you can do that,
+first way is simply to regenerate the OpenAPI schema by running the following command:
+
+```python
+from richapi import enrich_openapi
+from fastapi import FastAPI
+
+app = FastAPI()
+# add your routers ....
+app.openapi = enrich_openapi(app)
+```
+
+You can also compile the OpenAPI schema and save it to a file, by running this command from CLI:
+
+```bash
+richapi compile module.app:app
+```
+
+And then, you can run the following code to load the compiled OpenAPI schema:
+
+```python
+from richapi import load_openapi
+from fastapi import FastAPI
+
+app = FastAPI()
+
+with open("openapi.json") as open_api_json:
+    app.openapi = load_openapi(app, json.loads(open_api_json.read()))
+```
+
+!!! hint "My recommended way"
+
+    I personally recommend the second way, because it is better to have it compiled and saved to file, because there are static analysis running on the OpanAPI generator and your source code which isn't very ideal to be running in production.
+
+### Example
+
+Imagine this application;
+
+```python
+import random
+
+from fastapi import FastAPI
+
+from richapi.exc_parser.openapi import compile_openapi_from_fastapi, enrich_openapi
+from richapi.exc_parser.protocol import BaseHTTPException
+
+app = FastAPI()
+app.openapi = enrich_openapi(app)
+
+
+class InteralServer(BaseHTTPException):
+    status_code = 500
+    detail = "Internal server error"
+
+
+class NotFound(BaseHTTPException):
+    status_code = 501
+    detail = "Not found"
+
+
+class GatewayError(BaseHTTPException):
+    status_code = 502
+    detail = "Gateway error"
+
+
+def very_nested():
+    value = InteralServer
+    raise value
+
+
+def nested():
+    try:
+        very_nested()
+    except InteralServer:
+        raise NotFound
+
+
+@app.get("/home")
+def read_root() -> dict[str, str]:
+    if random.choice([True, False]):
+        nested()
+
+    elif random.choice([True, False]):
+        raise GatewayError()
+
+    return {"Hello": "World"}
+```
+
+What would you see WITHOUT RichAPI:
+![Screenshot](./images/without-richapi.png)
+
+After compiling OpenAPI WITH RichAPI (extended with all possible exceptions coming from your router):
+![Screenshot](./images/with-richapi.png)
+
+### Conventions (VERY IMPORTANT)
+
+There are some conventions about how to raise exceptions and etc. You may read the [conventions](conventions.md) to know more about them. The way library works is that it is a mini compiler using Abstract Syntax Tree and functions global to extract exceptions and their responses, and then it generates the OpenAPI schema from them. So there are limitations to what it can do, and you may need to follow the conventions to get the best out of it. Anything that is not following the conventions MAY be ignored by the compiler, and there is no plan to support them in the future, because it is not possible to support all the ways you can raise exceptions in Python... To give you an example, you may download a source code from internet and then use 'eval' function to run it dynamically, and there is no way to know what exceptions you may raise in that code, so it is impossible to support all the ways you can raise exceptions in Python.

richapi-0.1.0/makefile

@@ -0,0 +1,37 @@
+.PHONY: install
+install: ## Install the uv environment
+	@echo "🚀 Creating virtual environment using uv"
+	uv sync
+
+.PHONY: check
+check: ## Run the quality checks on the code
+	@echo "🚀 Running quality checks"
+	uv run ruff check .
+	uv run pyright .
+
+.PHONY: test
+test: ## Test the code with pytest
+	@echo "🚀 Testing code: Running pytest"
+	uv run pytest
+
+
+.PHONY: docs
+docs:  ## Build and serve the documentation
+	@echo "🚀 Testing documentation: Building and testing"
+	uv run mkdocs serve
+
+.PHONY: deploy-docs
+deploy-docs: ## Build and serve the documentation
+	@echo "🚀 Deploying documentation"
+	uv run python deploy_docs.py
+
+
+.PHONY: docs-test
+docs-test: ## Test if documentation can be built without warnings or errors
+	@uv run mkdocs build -s
+
+.PHONY: help
+help:
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help