{"id":19131381,"url":"https://github.com/panos-stavrianos/directuspywrapper","last_synced_at":"2025-09-08T16:32:41.148Z","repository":{"id":64115129,"uuid":"573552750","full_name":"panos-stavrianos/DirectusPyWrapper","owner":"panos-stavrianos","description":"DirectusPyWrapper is a Python library for interacting with the Directus headless CMS API","archived":false,"fork":false,"pushed_at":"2023-10-27T17:59:11.000Z","size":64,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-09T06:14:56.354Z","etag":null,"topics":["api","directus","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/panos-stavrianos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-12-02T18:36:36.000Z","updated_at":"2024-01-24T13:27:14.000Z","dependencies_parsed_at":"2023-02-17T05:30:47.327Z","dependency_job_id":"ed0f233a-5107-4661-a143-d49c08911b5a","html_url":"https://github.com/panos-stavrianos/DirectusPyWrapper","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panos-stavrianos%2FDirectusPyWrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panos-stavrianos%2FDirectusPyWrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panos-stavrianos%2FDirectusPyWrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panos-stavrianos%2FDirectusPyWrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/panos-stavrianos","download_url":"https://codeload.github.com/panos-stavrianos/DirectusPyWrapper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232327963,"owners_count":18506146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","directus","python"],"created_at":"2024-11-09T06:14:59.293Z","updated_at":"2025-01-03T11:24:19.917Z","avatar_url":"https://github.com/panos-stavrianos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DirectusPyWrapper\n\nDirectusPyWrapper is a Python wrapper for interacting with the Directus headless CMS API. It provides a convenient and\neasy-to-use interface for performing CRUD operations, querying data, and managing resources in Directus.\n\n## Features\n\n- Login and authentication handling\n- Reading and writing data from Directus collections\n- Filtering, sorting, and searching data\n- Aggregating data using aggregation operators\n- Creating, updating, and deleting items in Directus collections\n- Handling multiple users in the same session\n\nDependencies:\n- [Pydantic](https://pydantic-docs.helpmanual.io/): This library leverages Pydantic for data validation and parsing. Pydantic is a powerful tool in Python for ensuring data integrity and handling data validation with ease.\n\n- [Requests](https://docs.python-requests.org/en/master/): The library utilizes Requests, a widely-used HTTP library, for making HTTP requests. Requests simplifies the process of interacting with web services and APIs.\n\n\u003e Directus API:\n\u003e This library interacts with the [Directus API](https://docs.directus.io/reference/introduction.html).\n\u003e \n\u003e To make the most of this library, it is highly recommended to familiarize yourself with the Directus API documentation. Understanding the API's capabilities and endpoints will help you effectively utilize this library for seamless integration with Directus.\n\n\n## Disclaimer:\n\n**Please note that DirectusPyWrapper is currently under active development and may not be suitable for\nproduction use at this time.**\n\nWhile efforts are being made to ensure the library's stability and functionality, there\nmay still be bugs or limitations that need to be addressed. It is recommended to exercise caution and thoroughly test\nthe library before using it in a production environment. Feedback, bug reports, and contributions are highly appreciated\nto help improve the library's reliability and feature set.\n\n## Installation\n\nYou can install DirectusPyWrapper using pip:\n\n```shell\npip install git+https://github.com/panos-stavrianos/DirectusPyWrapper.git\n```\n\n\u003e PyPI package coming soon!\n\n## Authentication and Session Handling\n\n### Login\n\nCreate a Directus instance using email and password\n\n```python\nfrom DirectusPyWrapper import Directus\n\ndirectus = Directus(\"https://example.com\", email=\"user@example.com\", password=\"secret\")\n```\n\nAlternately create a Directus instance using the static token\n\n```python\nfrom DirectusPyWrapper import Directus\n\ndirectus = Directus(\"https://example.com\", token=\"static token\")\n```\n\n### Refresh Token\n\nIf you want to refresh the token you can use the `refresh` method\n\n```python\ndirectus.refresh()\n```\n\n\n### Logout\n\nLogout from Directus\n\n```python\ndirectus.logout()\n```\n\nAnother way is to use the `with` statement to automatically logout when the session ends\n\n```python\nwith Directus(url, email, password) as directus:\n    # do stuff\n```\n\n### Multiple Users in the Same Session\n\nYou can use multiple users in the same session by creating a new Directus instance by passing the session object\n\n```python\nsession = requests.Session()\ndirectus1 = Directus(url, token=token, session=session)\ndirectus2 = Directus(url, email=email, password=password, session=session)\n```\n\n## Collections\n\nThere are two ways to set a collection, either by passing the collection name as a string\nor by passing the collection as a Pydantic model.\n\nUsing the `items` method you can pass the collection name as a string\n\n```python\ndirectus.items(\"directus_users\")\n```\n\nUsing the `collection` method you can pass the collection as a `Pydantic` model\n\n```python\nfrom typing import Optional\nfrom pydantic import BaseModel\n\n\nclass User(BaseModel):\n    id: Optional[str]\n    first_name: Optional[str]\n    last_name: Optional[str]\n    avatar: Optional[str]\n    description: Optional[str]\n    email: Optional[str]\n    role: Optional[str] | Optional[Role]\n    status: Optional[str]\n    title: Optional[str]\n    token: Optional[str]\n\n    class Config:\n        collection = 'directus_users'\n\n\ndirectus.collection(User)\n```\n\n\u003e Don't forget to set the `collection` attribute in the `Config` class\n\nIf you go with the second option, you will get the responses as `Pydantic` models (auto parsing)\n\n\u003e The `items` and `collection` methods are returning a `DirectusRequest` object which is used to perform READ, CREATE,\n\u003e UPDATE and DELETE operations\n\n## Reading Data\n\nWhen you have the DirectusRequest object you can use the `read` method to get the data.\nThis will return a DirectusResponse object which contains the data.\n\n```python\ndirectus.items(\"directus_users\").read()\n```\n\n### Filtering\n\nFor an easy equality filter you can pass the field name and the value\n\n```python\ndirectus.items(\"directus_users\").filter(first_name=\"John\").read()\n```\n\nTo add multiple equality filters you can chain the `filter` method\n\n```python\ndirectus.items(\"directus_users\")\n.filter(first_name=\"John\")\n.filter(last_name=\"Doe\").read()\n```\n\nUsing it like this you chain the filters with `AND` operator\n\n\u003e Filtering is a little complicated, and it deserves its own section\n\u003e so a full guide will be added soon\n\n### Sorting\n\nYou can sort the data by passing the field name to the `sort` method\n\n```python\ndirectus.items(\"directus_users\").sort(\"first_name\", asc=True).read()\n```\n\nTo add multiple sorting fields you can chain the `sort` method\n\n```python\ndirectus.items(\"directus_users\")\n.sort(\"first_name\", asc=True)\n.sort(\"last_name\", asc=False).read()\n```\n\n### Limiting\n\nYou can limit the data by passing the limit to the `limit` method\n\n```python\ndirectus.items(\"directus_users\").limit(10).read()\n```\n\n### Aggregation\n\nYou can aggregate the data by passing the aggregation operator to the `aggregate` method\n\n```python\ndirectus.items(\"directus_users\").aggregate(AggregationOperators.Count).read()\n```\n\nThe available aggregation operators are:\n\n- Count\n- CountDistinct\n- CountAll\n- Sum\n- SumDistinct\n- Average\n- AverageDistinct\n- Minimum\n- Maximum\n\n### Grouping\n\nYou can group the data by passing the field names to the `group_by` method\n\n```python\ndirectus.items(\"directus_users\").group_by(\"first_name\", \"last_name\").read()\n```\n\n### Searching\n\nYou can search the data by passing the search term to the `search` method\n\n```python\ndirectus.items(\"directus_users\").search(\"John\").read()\n```\n\n### Selecting Fields\n\nYou can select the fields you want to get by passing the field names to the `fields` method\n\n```python\ndirectus.items(\"directus_users\").fields(\"first_name\", \"last_name\").read()\n```\n\n### Getting the Count Metadata\n\nYou can get the count of the data (total count and filtered count) calling `include_count`\n\n```python\ndirectus.items(\"directus_users\").include_count().read()\n```\n\n## Retrieving items\n\nAfter you call `read()` you get a `DirectusResponse` object which contains the data.\n\n- `item` for single item\n- `items` for multiple items\n\nGetting the data as a dictionary or a list of dictionaries\n\n```python\nresponse = directus.items(\"directus_users\").read()\nprint(response.item[\"first_name\"])\nprint(response.items)\n```\n\nIf you use `collection` you will get the data as a `Pydantic` object or a list of `Pydantic` objects\n\n```python\nresponse = directus.collection(User).read()\nprint(response.item.first_name)\nprint(response.items)\n```\n\n### Converting to Pydantic or to Dictionary\n\nApart from the auto parsing, you can manually convert the data to a `Pydantic` object or to a dictionary using:\n\n- `item_as(User)` or `items_as(User)`\n- `item_as_dict()` or `items_as_dict()`\n\n```python\nresponse = directus.items(\"directus_users\").read()\nprint(response.item_as(User))\n\nresponse = directus.collection(User).read()\nprint(response.item_as_dict())\n```\n\n## Creating Items\n\nFor creating the library do not support `Pydantic` models, you have to pass a dictionary\n\n- create_one(item: dict)\n- create_many(items: List[dict])\n\n\u003e Very soon the library will support `Pydantic` models for creating items\n\u003e and the `create_one` and `create_many` methods will be deprecated\n\u003e and replaced with the more broad `create` method\n\n```python\ndirectus.items(\"directus_users\").create_one({\n    \"first_name\": \"John\", \"last_name\": \"Doe\"\n})\n```\n\n```python\ndirectus.items(\"directus_users\").create_many(\n    [\n        {\"first_name\": \"John\", \"last_name\": \"Doe\"},\n        {\"first_name\": \"Jane\", \"last_name\": \"Doe\"}\n    ]\n)\n```\n\n## Updating Items\n\nFor updating the library do not support `Pydantic` models, you have to pass a dictionary\n\n- `update_one( id: str|int, item: dict)`\n- `update_many( ids: List[str|int], items: List[dict])`\n\n\u003e Supporting `Pydantic` models for updating items is not planned for now\n\n```python\ndirectus.items(\"directus_users\").update_one(1, {\n    \"first_name\": \"Red\",\n    \"last_name\": \"John\"\n})\n```\n\n```python\ndirectus.items(\"directus_users\").update_many(\n    [1, 2],\n    [\n        {\"first_name\": \"Jean-Luc\"},\n        {\"first_name\": \"Jane\", \"last_name\": \"Doe\"}\n    ]\n)\n```\n\n## Deleting Items\n\n\u003e Very soon the library will deprecate the `delete_one` and `delete_many` methods\n\u003e and replaced them with the more broad `delete` method, accepting a list or a single id\n\n- `delete_one(id: str|int)`\n- `delete_many(ids: List[str|int])`\n\n```python\ndirectus.items(\"directus_users\").delete_one(1)\n```\n\n```python\ndirectus.items(\"directus_users\").delete_many([1, 2])\n```\n\n## Roadmap\n\n- [ ] Develop comprehensive documentation and examples using the GitHub wiki.\n- [ ] Prepare a detailed filtering guide to assist users in utilizing filtering capabilities effectively.\n- [ ] Enhance testing procedures by dividing tests into multiple files for better organization.\n- [ ] Async Support: Introduce async functionality to the library, enabling users to leverage asynchronous programming for enhanced performance and responsiveness. This entails integrating async-compatible HTTP libraries and designing an intuitive async API that seamlessly integrates with async frameworks and workflows.\n- [ ] Implement support for `Pydantic` models in the create, update, and delete methods to facilitate structured data handling.\n- [ ] Explore possibilities to leverage `Pydantic` models for filtering, sorting, grouping, searching, and selecting specific fields, enhancing the flexibility and functionality of the library.\n\n    Something like this:\n    \n    ```python\n    directus.items(\"directus_users\").filter(User.first_name == \"John\").read()\n    ```\n\n\n\n## Contributing\n\nContributions to DirectusPyWrapper are welcome! If you find any issues or have suggestions for improvements, please open\nan issue. If you'd like to contribute code,\nyou can fork the repository and create a pull request with your changes.\n\n## License\n\nDirectusPyWrapper is licensed under the [MIT License](https://opensource.org/licenses/MIT).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpanos-stavrianos%2Fdirectuspywrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpanos-stavrianos%2Fdirectuspywrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpanos-stavrianos%2Fdirectuspywrapper/lists"}