# Midil Kit
A Python SDK for working with JSON:API specifications. This library provides a comprehensive set of tools for creating, validating, and manipulating JSON:API documents according to the [JSON:API specification](https://jsonapi.org/).
## Features
- **JSON:API Document Creation**: Easily create JSON:API compliant documents
- **Validation**: Built-in validation for JSON:API structures
- **Error Handling**: Comprehensive error document creation
- **Type Safety**: Full type hints and Pydantic models
- **Utility Functions**: Helper functions for common JSON:API operations
## Installation
### Using Poetry (Recommended)
```bash
poetry add midil-kit
```
### Using pip
```bash
pip install midil-kit
```
## Quick Start
```python
from jsonapi import (
JSONAPIDocument,
create_success_document,
create_error_document,
JSONAPIError
)
# Create a success document
data = {"id": "1", "type": "articles", "attributes": {"title": "JSON:API"}}
document = create_success_document(data)
# Create an error document
error = JSONAPIError(
status="422",
title="Validation Error",
detail="The request was invalid"
)
error_document = create_error_document([error])
# Access document properties
print(document.jsonapi.version) # "1.0"
print(document.data.attributes["title"]) # "JSON:API"
```
## Usage Examples
### Creating a Resource Document
```python
from jsonapi import JSONAPIDocument, ResourceObject
# Create a resource object
resource = ResourceObject(
id="1",
type="articles",
attributes={"title": "JSON:API", "content": "A specification for APIs"}
)
# Create a document with the resource
document = JSONAPIDocument(data=resource)
```
### Working with Relationships
```python
from jsonapi import JSONAPIDocument, ResourceObject, Relationship
# Create related resources
author = ResourceObject(id="1", type="authors", attributes={"name": "John Doe"})
article = ResourceObject(
id="1",
type="articles",
attributes={"title": "JSON:API"},
relationships={
"author": Relationship(data=author)
}
)
document = JSONAPIDocument(data=article)
```
### Error Handling
```python
from jsonapi import create_error_document, JSONAPIError, ErrorSource
# Create detailed error
error = JSONAPIError(
status="422",
title="Validation Error",
detail="The request was invalid",
source=ErrorSource(pointer="/data/attributes/title")
)
error_document = create_error_document([error])
```
## API Reference
### Core Classes
- `JSONAPIDocument`: Main document class for JSON:API responses
- `ResourceObject`: Represents a JSON:API resource
- `JSONAPIError`: Represents an error in a JSON:API response
- `Relationship`: Represents relationships between resources
### Utility Functions
- `create_success_document()`: Create a success document with data
- `create_error_document()`: Create an error document
- `create_resource_identifier()`: Create a resource identifier object
## Development
### Setup
1. Clone the repository:
```bash
git clone <repository-url>
cd midil-kit
```
2. Install dependencies:
```bash
poetry install
```
3. Install pre-commit hooks:
```bash
poetry run pre-commit install
```
### Running Tests
```bash
poetry run pytest
```
### Code Formatting
```bash
poetry run black .
poetry run isort .
```
### Type Checking
```bash
poetry run mypy .
```
### Changelog Management
The project includes automated changelog generation based on conventional commit messages.
**Preview changelog changes:**
```bash
make changelog-preview
```
**Update changelog with new commits:**
```bash
make changelog
```
**Create a new release:**
```bash
make create-release
```
**Bump version and prepare release:**
```bash
make release
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
### Commit Message Format
This project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification. Please use the following format for commit messages:
```
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```
**Types:**
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that do not affect the meaning of the code
- `refactor`: A code change that neither fixes a bug nor adds a feature
- `test`: Adding missing tests or correcting existing tests
- `chore`: Changes to the build process or auxiliary tools
**Scopes:**
- `jsonapi`: JSON:API core functionality
- `docs`: Documentation
- `ci`: Continuous integration
- `deps`: Dependencies
**Examples:**
```
feat(jsonapi): add support for sparse fieldsets
fix(jsonapi): resolve validation error in relationship serialization
docs: update README with usage examples
test: add tests for error document creation
chore: update dependencies
```
For breaking changes, start the commit body with `BREAKING CHANGE:`:
```
feat(jsonapi): remove deprecated ResourceObject constructor
BREAKING CHANGE: The ResourceObject constructor signature has changed
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
### 0.1.0
- Initial release
- Basic JSON:API document creation and validation
- Error handling utilities
- Type-safe Pydantic models
Raw data
{
"_id": null,
"home_page": null,
"name": "midil-kit",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "midil, midil-kit, jsonapi-sdk, jsonapi, jsonapi-sdk",
"author": "Engr. Michael Kofi Armah",
"author_email": "michael.armah@midil.io",
"download_url": "https://files.pythonhosted.org/packages/08/4d/3bc8992d54be6e97e141824e5176e39ba6852b9a2103f4f75b9f0ceca9e5/midil_kit-1.0.4.tar.gz",
"platform": null,
"description": "# Midil Kit\n\nA Python SDK for working with JSON:API specifications. This library provides a comprehensive set of tools for creating, validating, and manipulating JSON:API documents according to the [JSON:API specification](https://jsonapi.org/).\n\n## Features\n\n- **JSON:API Document Creation**: Easily create JSON:API compliant documents\n- **Validation**: Built-in validation for JSON:API structures\n- **Error Handling**: Comprehensive error document creation\n- **Type Safety**: Full type hints and Pydantic models\n- **Utility Functions**: Helper functions for common JSON:API operations\n\n## Installation\n\n### Using Poetry (Recommended)\n\n```bash\npoetry add midil-kit\n```\n\n### Using pip\n\n```bash\npip install midil-kit\n```\n\n## Quick Start\n\n```python\nfrom jsonapi import (\n JSONAPIDocument,\n create_success_document,\n create_error_document,\n JSONAPIError\n)\n\n# Create a success document\ndata = {\"id\": \"1\", \"type\": \"articles\", \"attributes\": {\"title\": \"JSON:API\"}}\ndocument = create_success_document(data)\n\n# Create an error document\nerror = JSONAPIError(\n status=\"422\",\n title=\"Validation Error\",\n detail=\"The request was invalid\"\n)\nerror_document = create_error_document([error])\n\n# Access document properties\nprint(document.jsonapi.version) # \"1.0\"\nprint(document.data.attributes[\"title\"]) # \"JSON:API\"\n```\n\n## Usage Examples\n\n### Creating a Resource Document\n\n```python\nfrom jsonapi import JSONAPIDocument, ResourceObject\n\n# Create a resource object\nresource = ResourceObject(\n id=\"1\",\n type=\"articles\",\n attributes={\"title\": \"JSON:API\", \"content\": \"A specification for APIs\"}\n)\n\n# Create a document with the resource\ndocument = JSONAPIDocument(data=resource)\n```\n\n### Working with Relationships\n\n```python\nfrom jsonapi import JSONAPIDocument, ResourceObject, Relationship\n\n# Create related resources\nauthor = ResourceObject(id=\"1\", type=\"authors\", attributes={\"name\": \"John Doe\"})\narticle = ResourceObject(\n id=\"1\",\n type=\"articles\",\n attributes={\"title\": \"JSON:API\"},\n relationships={\n \"author\": Relationship(data=author)\n }\n)\n\ndocument = JSONAPIDocument(data=article)\n```\n\n### Error Handling\n\n```python\nfrom jsonapi import create_error_document, JSONAPIError, ErrorSource\n\n# Create detailed error\nerror = JSONAPIError(\n status=\"422\",\n title=\"Validation Error\",\n detail=\"The request was invalid\",\n source=ErrorSource(pointer=\"/data/attributes/title\")\n)\n\nerror_document = create_error_document([error])\n```\n\n## API Reference\n\n### Core Classes\n\n- `JSONAPIDocument`: Main document class for JSON:API responses\n- `ResourceObject`: Represents a JSON:API resource\n- `JSONAPIError`: Represents an error in a JSON:API response\n- `Relationship`: Represents relationships between resources\n\n### Utility Functions\n\n- `create_success_document()`: Create a success document with data\n- `create_error_document()`: Create an error document\n- `create_resource_identifier()`: Create a resource identifier object\n\n## Development\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd midil-kit\n```\n\n2. Install dependencies:\n```bash\npoetry install\n```\n\n3. Install pre-commit hooks:\n```bash\npoetry run pre-commit install\n```\n\n### Running Tests\n\n```bash\npoetry run pytest\n```\n\n### Code Formatting\n\n```bash\npoetry run black .\npoetry run isort .\n```\n\n### Type Checking\n\n```bash\npoetry run mypy .\n```\n\n### Changelog Management\n\nThe project includes automated changelog generation based on conventional commit messages.\n\n**Preview changelog changes:**\n```bash\nmake changelog-preview\n```\n\n**Update changelog with new commits:**\n```bash\nmake changelog\n```\n\n**Create a new release:**\n```bash\nmake create-release\n```\n\n**Bump version and prepare release:**\n```bash\nmake release\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n### Commit Message Format\n\nThis project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification. Please use the following format for commit messages:\n\n```\n<type>(<scope>): <description>\n\n[optional body]\n\n[optional footer(s)]\n```\n\n**Types:**\n- `feat`: A new feature\n- `fix`: A bug fix\n- `docs`: Documentation only changes\n- `style`: Changes that do not affect the meaning of the code\n- `refactor`: A code change that neither fixes a bug nor adds a feature\n- `test`: Adding missing tests or correcting existing tests\n- `chore`: Changes to the build process or auxiliary tools\n\n**Scopes:**\n- `jsonapi`: JSON:API core functionality\n- `docs`: Documentation\n- `ci`: Continuous integration\n- `deps`: Dependencies\n\n**Examples:**\n```\nfeat(jsonapi): add support for sparse fieldsets\nfix(jsonapi): resolve validation error in relationship serialization\ndocs: update README with usage examples\ntest: add tests for error document creation\nchore: update dependencies\n```\n\nFor breaking changes, start the commit body with `BREAKING CHANGE:`:\n```\nfeat(jsonapi): remove deprecated ResourceObject constructor\n\nBREAKING CHANGE: The ResourceObject constructor signature has changed\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\n### 0.1.0\n- Initial release\n- Basic JSON:API document creation and validation\n- Error handling utilities\n- Type-safe Pydantic models\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python SDK for working with JSON:API specifications",
"version": "1.0.4",
"project_urls": null,
"split_keywords": [
"midil",
" midil-kit",
" jsonapi-sdk",
" jsonapi",
" jsonapi-sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fef873e894641aebad012a7a7e8424c7f7acaac64f9febeb1760bc68c676dfa6",
"md5": "81fc244e130e73e05d70e1052c987597",
"sha256": "c989d684073bcb483f1de63f2a7b3fc1bdcd6da2a3050e90cba0a2dfd2cf26d7"
},
"downloads": -1,
"filename": "midil_kit-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81fc244e130e73e05d70e1052c987597",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 17820,
"upload_time": "2025-07-14T01:37:11",
"upload_time_iso_8601": "2025-07-14T01:37:11.887607Z",
"url": "https://files.pythonhosted.org/packages/fe/f8/73e894641aebad012a7a7e8424c7f7acaac64f9febeb1760bc68c676dfa6/midil_kit-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "084d3bc8992d54be6e97e141824e5176e39ba6852b9a2103f4f75b9f0ceca9e5",
"md5": "c137f3c3b6111d12911f1b0137b02afb",
"sha256": "8ad7fb035ba016d30e8bc3a4aefa64861fbf5afbffca49feb0524c6621405b56"
},
"downloads": -1,
"filename": "midil_kit-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "c137f3c3b6111d12911f1b0137b02afb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 16779,
"upload_time": "2025-07-14T01:37:13",
"upload_time_iso_8601": "2025-07-14T01:37:13.179247Z",
"url": "https://files.pythonhosted.org/packages/08/4d/3bc8992d54be6e97e141824e5176e39ba6852b9a2103f4f75b9f0ceca9e5/midil_kit-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 01:37:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "midil-kit"
}
JSON