Merge pull request #104 from tarsil/feature/annotations

Add API Reference

docs/overrides/home.html

@@ -52,8 +52,8 @@ <h1 class="display-4 fw-bold text-start d-xl-flex mb-5">Complex databases done r
 <code class="language-python">
 import saffier
 
-database = Database("sqlite:///db.sqlite")
-registry = Registry(database=database)
+database = saffier.Database("sqlite:///db.sqlite")
+registry = saffier.Registry(database=database)
 
 class User(saffier.Model):
     id = saffier.IntegerField(primary_key=True)

docs/references/database.md

@@ -0,0 +1,14 @@
+# **`Database`** class
+
+
+::: saffier.Database
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"
+        - "!^__aenter__"
+        - "!^__aexit__"
+        - "!^SUPPORTED_BACKENDS"
+        - "!^DIRECT_URL_SCHEME"
+        - "!^MANDATORY_FIELDS"

docs/references/fields.md

@@ -0,0 +1,9 @@
+# **`BaseField`** class
+
+
+::: saffier.core.db.fields.base.Field
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"

docs/references/foreignkey.md

@@ -0,0 +1,10 @@
+# **`ForeignKey`** class
+
+
+::: saffier.ForeignKey
+    options:
+        filters:
+        - "!^_type"
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"

docs/references/index.md

@@ -0,0 +1,6 @@
+# API Reference
+
+Here lies all the useful API references for the classes, functions and attributes of all
+parts you can use in your application development.
+
+If you want to start with **Edgy** you should always [start here](https://edgy.tarsild.io/edgy).

docs/references/manager.md

@@ -0,0 +1,9 @@
+# **`Manager`** class
+
+
+::: saffier.Manager
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"

docs/references/many-to-many.md

@@ -0,0 +1,10 @@
+# **`ManyToMany`** class
+
+
+::: saffier.ManyToManyField
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"
+        - "!^_type"

docs/references/models.md

@@ -0,0 +1,10 @@
+# **`Model`** class
+
+
+::: saffier.Model
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__dict__"
+        - "!^__repr__"
+        - "!^__str__"

docs/references/one-to-one.md

@@ -0,0 +1,11 @@
+# **`OneToOne`** class
+
+
+::: saffier.OneToOneField
+    options:
+        filters:
+        - "!^_type"
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"
+        - "!^__new__"

docs/references/queryset.md

@@ -0,0 +1,14 @@
+# **`QuerySet`** class
+
+::: saffier.QuerySet
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__await__"
+        - "!^__class_getitem__"
+        - "!^__get__"
+        - "!^ESCAPE_CHARACTERS"
+        - "!^m2m_related"
+        - "!^pkname"
+        - "!^_m2m_related"

docs/references/reflect-model.md

@@ -0,0 +1,10 @@
+# **`ReflectModel`** class
+
+
+::: saffier.ReflectModel
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__dict__"
+        - "!^__repr__"
+        - "!^__str__"

docs/references/registry.md

@@ -0,0 +1,9 @@
+# **`Registry`** class
+
+
+::: saffier.Registry
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"

docs/references/schemas.md

@@ -0,0 +1,14 @@
+# **`Schema`** class
+
+
+::: saffier.core.connection.schemas.Schema
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"
+        - "!^__aenter__"
+        - "!^__aexit__"
+        - "!^SUPPORTED_BACKENDS"
+        - "!^DIRECT_URL_SCHEME"
+        - "!^MANDATORY_FIELDS"

docs/references/signals.md

@@ -0,0 +1,9 @@
+# **`Signal`** class
+
+
+::: saffier.Signal
+    options:
+        filters:
+        - "!^model_config"
+        - "!^__slots__"
+        - "!^__getattr__"

docs/release-notes.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Release Notes
 
 ## 1.0.0

docs/saffier.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Saffier
 
 <p align="center">

mkdocs.yml

@@ -27,68 +27,114 @@ theme:
     - search.suggest
     - search.highlight
     - content.tabs.link
+    - content.code.copy
+    - content.code.annotate
+    - content.tooltips
+    - content.code.select
+    - navigation.indexes
+    - navigation.path
+    - navigation.tabs
 
 repo_name: tarsil/saffier
 repo_url: https://github.com/tarsil/saffier
 edit_uri: ""
 plugins:
   - search
+  - meta-descriptions:
+      export_csv: false
+      quiet: false
+      enable_checks: false
+      min_length: 50
+      max_length: 160
+      trim: false
   - markdownextradata:
       data: data
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            extensions:
+              - griffe_typingdoc
+            show_root_heading: true
+            show_if_no_docstring: true
+            preload_modules: [databasez]
+            inherited_members: true
+            members_order: source
+            separate_signature: true
+            unwrap_annotated: true
+            filters: ["!^_"]
+            merge_init_into_class: true
+            docstring_section_style: spacy
+            signature_crossrefs: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
 
 nav:
   - Home: "index.md"
   - Saffier: "saffier.md"
-  - Models: "models.md"
-  - Declarative Models: "declarative-models.md"
-  - Reflection: "reflection.md"
-  - Managers: "managers.md"
-  - Fields: "fields.md"
-  - Queries:
-      - Queries: "queries/queries.md"
-      - Related Name: "queries/related-name.md"
-      - ManyToMany: "queries/many-to-many.md"
-      - Prefetch Related: "queries/prefetch.md"
-  - Signals: "signals.md"
-  - Transactions: "transactions.md"
-  - Relationships: "relationships.md"
-  - Connection: "connection.md"
-  - Tenancy:
-      - Saffier: "tenancy/saffier.md"
-      - Contrib: "tenancy/contrib.md"
-  - Registry: "registry.md"
-  - Shell Support: "shell.md"
-  - Settings: "settings.md"
-  - Exceptions: "exceptions.md"
-  - Migrations:
-      - Discovery: "migrations/discovery.md"
-      - Migrations: "migrations/migrations.md"
-  - Tips and Tricks: "tips-and-tricks.md"
-  - Extras: "extras.md"
-  - Test Client: "test-client.md"
-  - Saffier People: "saffier-people.md"
-  - Contributing: "contributing.md"
-  - Sponsorship: "sponsorship.md"
+  - Core:
+      - Models: "models.md"
+      - Declarative Models: "declarative-models.md"
+      - Reflection: "reflection.md"
+      - Managers: "managers.md"
+      - Fields: "fields.md"
+      - Queries:
+          - Queries: "queries/queries.md"
+          - Related Name: "queries/related-name.md"
+          - ManyToMany: "queries/many-to-many.md"
+          - Prefetch Related: "queries/prefetch.md"
+      - Transactions: "transactions.md"
+  - Features:
+      - Signals: "signals.md"
+      - Relationships: "relationships.md"
+      - Connection: "connection.md"
+      - Tenancy:
+          - Saffier: "tenancy/saffier.md"
+          - Contrib: "tenancy/contrib.md"
+      - Registry: "registry.md"
+      - Shell Support: "shell.md"
+      - Migrations:
+          - Discovery: "migrations/discovery.md"
+          - Migrations: "migrations/migrations.md"
+      - Settings: "settings.md"
+  - Extras:
+      - Exceptions: "exceptions.md"
+      - Tips and Tricks: "tips-and-tricks.md"
+      - Extras: "extras.md"
+      - Test Client: "test-client.md"
+  - API Reference:
+      - "references/index.md"
+      - Model: "references/models.md"
+      - ReflectModel: "references/reflect-model.md"
+      - Manager: "references/manager.md"
+      - QuerySet: "references/queryset.md"
+      - Signals: "references/signals.md"
+      - Fields:
+          - Field: "references/fields.md"
+          - OneToOne: "references/one-to-one.md"
+          - ForeignKey: "references/foreignkey.md"
+          - ManyToMany: "references/many-to-many.md"
+      - Registry: "references/registry.md"
+      - Schema: "references/schemas.md"
+      - Database: "references/database.md"
+  - About:
+      - Saffier People: "saffier-people.md"
+      - Contributing: "contributing.md"
+      - Sponsorship: "sponsorship.md"
   - Release Notes: "release-notes.md"
 markdown_extensions:
   - attr_list
   - toc:
       permalink: true
-  - markdown.extensions.codehilite:
-      guess_lang: false
   - mdx_include:
       base_path: docs
   - admonition
-  - codehilite
   - extra
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format ""
-  - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
   - pymdownx.tabbed:
       alternate_style: true
   - md_in_html

pyproject.toml

@@ -102,13 +102,15 @@ dev = [
 ]
 
 doc = [
+    "griffe-typingdoc>=0.2.2",
     "mkautodoc>=0.2.0,<0.3.0",
-    "mkdocs>=1.4.2,<2.0.0",
-    "mkdocs-material==9.4.2",
-    "mdx-include>=1.4.1,<2.0.0",
-    "mkdocs-markdownextradata-plugin>=0.1.7,<0.3.0",
-    "mkdocstrings>=0.19.0,<0.24.0",
-    "pyyaml>=5.3.1,<7.0.0",
+    "mkdocs>=1.1.2,<2.0.0",
+    "mkdocs-material>=9.4.4,<10.0.0",
+    "mdx-include>=1.4.2,<2.0.0",
+    "mkdocs-markdownextradata-plugin>=0.2.5,<0.3.0",
+    "mkdocs-meta-descriptions-plugin>=2.3.0",
+    "mkdocstrings[python]>=0.23.0,<0.30.0",
+    "pyyaml>=6.0,<7.0.0",
 ]
 
 testing = ["sqlalchemy_utils>=0.40.0"]

saffier/core/connection/database.py

@@ -1 +1,31 @@
-from databasez import Database as Database  # noqa
+from databasez import Database as Databasez  # noqa
+from databasez import DatabaseURL as DatabaseURL  # noqa
+
+
+class Database(Databasez):
+    """
+    An abstraction on the top of the EncodeORM databases.Database object.
+
+    This object allows to pass also a configuration dictionary in the format of
+
+    ```python
+    DATABASEZ_CONFIG = {
+        "connection": {
+            "credentials": {
+                "scheme": 'sqlite', "postgres"...
+                "host": ...,
+                "port": ...,
+                "user": ...,
+                "password": ...,
+                "database": ...,
+                "options": {
+                    "driver": ...
+                    "ssl": ...
+                }
+            }
+        }
+    }
+    ```
+    """
+
+    ...

saffier/core/connection/registry.py

@@ -20,10 +20,6 @@ class Registry:
     """
 
     def __init__(self, database: Database, **kwargs: Any) -> None:
-        assert isinstance(
-            database, Database
-        ), "database must be an instance of saffier.core.connection.Database"
-
         self.database: Database = database
         self.models: Dict[str, Any] = {}
         self.reflected: Dict[str, Any] = {}