feat: pydantic

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v5
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+      - run: |
+          uv sync --dev
+          zensical build --clean
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.github/workflows/publish.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@v6
         with:
-            version: ">=0.7.21,<0.8"
+            version: ">=0.9.13,<0.10"
 
       - name: Set SETUPTOOLS_SCM_PRETEND_VERSION
         run: echo "SETUPTOOLS_SCM_PRETEND_VERSION=${GITHUB_REF##*/}" >> $GITHUB_ENV

.github/workflows/test.yml

@@ -16,19 +16,24 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Setup uv
         uses: astral-sh/setup-uv@v6
         with:
-            version: ">=0.7.21,<0.8"
+            version: ">=0.9.13,<0.10"
       - name: Set up Python ${{ matrix.python-version }}
         env:
           PYTHON_VERSION: ${{ matrix.python-version }}
         run: uv venv --python $PYTHON_VERSION
       - name: Install Dependencies
         run: uv sync --dev --locked
       - name: Run Tests
-        run: uv run pytest
+        run: uv run pytest --cov=./src/apmodel --cov-branch --cov-report=xml
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.pre-commit-config.yaml

@@ -0,0 +1,72 @@
+repos:
+- hooks:
+  - additional_dependencies:
+    - cryptography>=45.0.6
+    - git-cliff>=2.10.0
+    - mkdocstrings-python>=2.0.1
+    - multiformats>=0.3.1.post4
+    - pydantic>=2.12.5
+    - pyld[aiohttp,requests]>=2.0.4
+    - pyrefly>=0.46.0
+    - pytest-cov>=7.0.0
+    - pytest>=8.4.1
+    - pyyaml>=6.0.3
+    - typing-extensions>=4.15.0
+    - zensical>=0.0.13
+    args:
+    - --fix
+    description: Run 'ruff' for extremely fast Python linting
+    entry: ruff check --force-exclude
+    id: ruff
+    language: python
+    minimum_pre_commit_version: 2.9.2
+    name: ruff
+    require_serial: true
+    types_or:
+    - python
+    - pyi
+  - additional_dependencies:
+    - cryptography>=45.0.6
+    - git-cliff>=2.10.0
+    - mkdocstrings-python>=2.0.1
+    - multiformats>=0.3.1.post4
+    - pydantic>=2.12.5
+    - pyld[aiohttp,requests]>=2.0.4
+    - pyrefly>=0.46.0
+    - pytest-cov>=7.0.0
+    - pytest>=8.4.1
+    - pyyaml>=6.0.3
+    - typing-extensions>=4.15.0
+    - zensical>=0.0.13
+    args: []
+    description: Run 'ruff format' for extremely fast Python formatting
+    entry: ruff format --force-exclude
+    id: ruff-format
+    language: python
+    minimum_pre_commit_version: 2.9.2
+    name: ruff-format
+    require_serial: true
+    types_or:
+    - python
+    - pyi
+  repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.1.6
+- hooks:
+  - additional_dependencies:
+    - cryptography>=45.0.6
+    - git-cliff>=2.10.0
+    - mkdocstrings-python>=2.0.1
+    - multiformats>=0.3.1.post4
+    - pydantic>=2.12.5
+    - pyld[aiohttp,requests]>=2.0.4
+    - pyrefly>=0.46.0
+    - pytest-cov>=7.0.0
+    - pytest>=8.4.1
+    - pyyaml>=6.0.3
+    - typing-extensions>=4.15.0
+    - zensical>=0.0.13
+    id: pyrefly-check
+    name: Pyrefly (type checking)
+    pass_filenames: false
+  repo: https://github.com/facebook/pyrefly-pre-commit
+  rev: 0.46.0

.zed/settings.json

@@ -0,0 +1,36 @@
+{
+    "languages": {
+        "Python": {
+            "language_servers": ["ruff", "pyrefly"]
+        }
+    },
+    "lsp": {
+        "pyrefly": {
+            "binary": {
+                "path": ".venv/bin/pyrefly",
+                "arguments": ["lsp"]
+            },
+            "settings": {
+                "python": {
+                    "pythonPath": ".venv/bin/python"
+                },
+                "pyrefly": {
+                    "project_includes": ["src/**/*.py", "tests/**/*.py"],
+                    "project_excludes": ["**/.[!/.]*", "**/*venv/**"],
+                    "search_path": ["src"],
+                    "ignore_errors_in_generated_code": true
+                }
+            }
+        },
+        "ruff": {
+            "initialization_options": {
+                "settings": {
+                    "lineLength": 80,
+                    "lint": {
+                        "extendSelect": ["I"]
+                    }
+                }
+            }
+        }
+    }
+}

AGENTS.md

@@ -5,7 +5,7 @@ apmodel provides model implementations for Activity Streams 2.0, CryptographicKe
 
 ## Features
 - A `load` function that automatically reads the `type` key from JSON and converts it to the correct model. It returns the original JSON if no matching model is found.
-- If a key from the JSON does not correspond to a field in the model, it is added to the model's `_extra` dictionary.
+- If a key from the JSON does not correspond to a field in the model, it is added to the model's `model_extra` dictionary.
 
 ## How to run scripts
 This project uses [Task](https://taskfile.dev/) for running scripts. You will need to install it to use the commands below.

CHANGELOG.md

@@ -73,7 +73,7 @@
 - *(question)* Prevent side effects in Question.to_json
 - *(tombstone)* Prevent side effects in Tombstone.to_json
 - Use `ctx.full_context` instead of `ctx.json`
-- Initialize aggregated_context as a new LDContext instance, copied from self._context
+- Initialize aggregated_context as a new LDContext instance, copied from self.context
 - Use PrivateFormat.PKCS1 instead of PrivateFormat.Raw in rsa-priv
 - *(cid)* Handle 'Z' timezone in DataIntegrityProof
 - Fixes for violation of the Liskov Substitution Principle

CLAUDE.md

@@ -5,7 +5,7 @@ apmodel provides model implementations for Activity Streams 2.0, CryptographicKe
 
 ## Features
 - A `load` function that automatically reads the `type` key from JSON and converts it to the correct model. It returns the original JSON if no matching model is found.
-- If a key from the JSON does not correspond to a field in the model, it is added to the model's `_extra` dictionary.
+- If a key from the JSON does not correspond to a field in the model, it is added to the model's `model_extra` dictionary.
 
 ## How to run scripts
 This project uses [Task](https://taskfile.dev/) for running scripts. You will need to install it to use the commands below.

GEMINI.md

@@ -5,7 +5,7 @@ apmodel provides model implementations for Activity Streams 2.0, CryptographicKe
 
 ## Features
 - A `load` function that automatically reads the `type` key from JSON and converts it to the correct model. It returns the original JSON if no matching model is found.
-- If a key from the JSON does not correspond to a field in the model, it is added to the model's `_extra` dictionary.
+- If a key from the JSON does not correspond to a field in the model, it is added to the model's `model_extra` dictionary.
 
 ## How to run scripts
 This project uses [Task](https://taskfile.dev/) for running scripts. You will need to install it to use the commands below.

README.md

@@ -1,7 +1,105 @@
 # apmodel
-ActivityStreams 2.0 and nodeinfo 2.0/2.1 implementation for Python.
-## Other ActivityPub Tools
-- [apsig: Signature implementation used in ActivityPub](https://github.com/AmaseCocoa/apsig)
-- [apkit: Powerful Toolkit for ActivityPub Implementations](https://github.com/AmaseCocoa/apkit)
-## Links
-- [Official Fedi Account](https://hollo.amase.cc/@apkit)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/apmodel)](https://pypi.org/project/apmodel)
+[![Tests](https://github.com/fedi-libs/apmodel/actions/workflows/test.yml/badge.svg)](https://github.com/fedi-libs/apmodel/actions/workflows/test.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/fedi-libs/apmodel/develop.svg)](https://results.pre-commit.ci/latest/github/fedi-libs/apmodel/develop)
+
+apmodel is a Python library that provides model implementations for various decentralized social web protocols.
+
+It is designed to easily parse and handle JSON data from sources like Mastodon, Misskey, and other Fediverse software.
+
+## Features
+
+- **Automatic Model Resolution**: The `apmodel.load` function automatically deserializes a JSON object into the appropriate Python object by reading its `type` field. If no matching model is found, the original dictionary is returned.
+- **Flexible Deserialization**: Any properties in the JSON that do not have a corresponding field in the model are collected into an `model_extra` dictionary. This ensures no data is lost.
+- **Type Hinting**: Fully type-hinted for a better development experience and robust static analysis.
+
+## Installation
+
+```bash
+pip install apmodel
+
+# uv
+uv add apmodel
+```
+
+## Usage
+
+Here is a basic example of how to parse an ActivityStreams 2.0 `Note` object from a JSON string.
+
+```python
+import apmodel
+
+# Example JSON from a Fediverse server
+json_data = {
+  "@context": "https://www.w3.org/ns/activitystreams",
+  "id": "https://example.com/users/alice/statuses/1",
+  "type": "Note",
+  "published": "2023-12-25T12:00:00Z",
+  "attributedTo": "https://example.com/users/alice",
+  "content": "<p>Hello, world!</p>",
+  "to": ["https://www.w3.org/ns/activitystreams#Public"],
+  "cc": ["https://example.com/users/alice/followers"]
+}
+
+# Load the JSON into an apmodel object
+obj = apmodel.load(json_data)
+
+# Now you can access properties with type safety
+if isinstance(obj, apmodel.vocab.Note):
+    print(f"Type: {obj.type}")
+    print(f"Content: {obj.content}")
+    print(f"Published: {obj.published}")
+
+# >> Type: Note
+# >> Content: <p>Hello, world!</p>
+# >> Published: 2023-12-25 12:00:00+00:00
+```
+
+## Documentation
+
+https://fedi-libs.github.io/apmodel
+
+## Supported Specifications
+
+`apmodel` provides models for the following specifications:
+
+- **Activity Streams 2.0**: Core types like `Object`, `Activity`, `Collection`, and `Link`.
+- **Activity Vocabulary**: All types.
+- **Security Vocabulary v1**: `CryptographicKey` (`Key`).
+- **Controlled Identifiers v1.0**: `Multikey` and `DataIntegrityProof`.
+- **schema.org**: `PropertyValue`.
+- **NodeInfo 2.0/2.1**
+- **Litepub**: `EmojiReact`
+- **Others**: `Emoji` and `Hashtag`
+
+## Development
+
+This project uses [Task](https://taskfile.dev/) for running scripts. You need to install it first.
+
+- **Setup dev environment**:
+
+    ```bash
+    task
+    ```
+
+- **Run tests with Pytest**:
+
+    ```bash
+    task test
+    ```
+
+- **Build packages for PyPI**:
+
+    ```bash
+    task build
+    ```
+
+- **Development Document**:
+    ```bash
+    task docs:dev
+    ```
+
+## License
+
+MIT License

Taskfile.yml

@@ -7,7 +7,11 @@ tasks:
     silent: true
   test:
     cmds:
-      - uv run pytest
+      - uv run pytest --cov=./src/apmodel
+    silent: true
+  docs:dev:
+    cmds:
+      - uv run zensical serve
     silent: true
   build:
     cmds:

docs/api/core.md

@@ -0,0 +1,35 @@
+# Core Types
+
+This section documents the fundamental building blocks of the ActivityStreams models in `apmodel`.
+
+::: apmodel.core.object.Object
+    options:
+      show_root_heading: true
+
+::: apmodel.core.activity.Activity
+    options:
+      show_root_heading: true
+
+::: apmodel.core.activity.IntransitiveActivity
+    options:
+      show_root_heading: true
+
+::: apmodel.core.link.Link
+    options:
+      show_root_heading: true
+
+::: apmodel.core.collection.Collection
+    options:
+      show_root_heading: true
+
+::: apmodel.core.collection.OrderedCollection
+    options:
+      show_root_heading: true
+
+::: apmodel.core.collection.CollectionPage
+    options:
+      show_root_heading: true
+
+::: apmodel.core.collection.OrderedCollectionPage
+    options:
+      show_root_heading: true