{"id":46593028,"url":"https://github.com/cesbit/aiogcd","last_synced_at":"2026-04-02T13:21:16.453Z","repository":{"id":42694458,"uuid":"91817381","full_name":"cesbit/aiogcd","owner":"cesbit","description":"Async Google Cloud Datastore API","archived":false,"fork":false,"pushed_at":"2025-11-25T15:38:17.000Z","size":167,"stargazers_count":29,"open_issues_count":3,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-12-22T01:27:40.970Z","etag":null,"topics":["asyncio","google-cloud","google-cloud-datastore","orm-layer"],"latest_commit_sha":null,"homepage":null,"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/cesbit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"cesbit"}},"created_at":"2017-05-19T15:01:34.000Z","updated_at":"2025-11-25T15:35:37.000Z","dependencies_parsed_at":"2023-07-15T23:46:49.187Z","dependency_job_id":null,"html_url":"https://github.com/cesbit/aiogcd","commit_stats":null,"previous_names":["transceptor-technology/aiogcd"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/cesbit/aiogcd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cesbit%2Faiogcd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cesbit%2Faiogcd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cesbit%2Faiogcd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cesbit%2Faiogcd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cesbit","download_url":"https://codeload.github.com/cesbit/aiogcd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cesbit%2Faiogcd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30216495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T13:35:13.914Z","status":"ssl_error","status_checked_at":"2026-03-07T13:35:13.569Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["asyncio","google-cloud","google-cloud-datastore","orm-layer"],"created_at":"2026-03-07T14:02:23.731Z","updated_at":"2026-04-02T13:21:16.446Z","avatar_url":"https://github.com/cesbit.png","language":"Python","funding_links":["https://github.com/sponsors/cesbit"],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/cesbit/aiogcd/workflows/CI/badge.svg)](https://github.com/cesbit/aiogcd/actions)\n[![Release Version](https://img.shields.io/github/release/cesbit/aiogcd)](https://github.com/cesbit/aiogcd/releases)\n\nAsync Google Cloud Datastore API\n================================\nPackage aiogcd includes both a Connector and ORM layer for communicating with Google Cloud Datastore without using App Engine.\n\u003e By design the connector has no dependencies to the ORM layer. This makes it possible to use the\nconnector without the orm layer if this is preferred.\n\n---------------------------------------\n  * [Installation](#installation)\n  * [Connector](#connector)\n    * [Quick usage](#quick-usage)\n    * [Entity](#entity)\n  * [ORM](#orm-layer)\n  * [Namespaces](#namespaces)\n  * [Emulator](#emulater)\n\n---------------------------------------\n\n## Installation\nThe most easy way is to install this package using PyPI:\n```\npip install aiogcd\n```\n\nTo install from source code:\n```\npython setup.py install\n```\n\n## Connector\nThe connector is designed so that it can be used without using the ORM layer.\n\n### Quick usage:\n\n```python\nimport asyncio\nfrom aiogcd.connector import GcdConnector\n\nasync def example():\n\n    # create a Google Cloud Datastore connector\n    gcd = GcdConnector(\n        project_id='my_project_id_or_app_id',\n        client_id='my_client_id',\n        client_secret='my_client_secret',\n        token_file='token_file.json')\n\n    # make at least one call to gcd using the connect() function. this function\n    # creates the token file in case it does not exists and might prompt the\n    # user for a code.\n    await gcd.connect()\n\nasyncio.run(example())\n```\n\n### Entity\n\nCreate a new entity:\n\n```python\nimport asyncio\nfrom aiogcd.connector import GcdConnector\nfrom aiogcd.connector.entity import Entity\n\nasync def insert_alice():\n    gcd = GcdConnector(\n        project_id='my_project_id_or_app_id',\n        client_id='my_client_id',\n        client_secret='my_client_secret',\n        token_file='token_file.json')\n\n    await gcd.connect()\n\n    alice = Entity({\n        'properties': {\n            'name': {'stringValue': 'Alice'},\n            'age': {'integerValue': 26}\n        },\n        'key': {\n            'partitionId': {'projectId': gcd.project_id},\n            'path': [{'kind': 'User'}]\n        }\n    })\n\n    await gcd.insert_entity(alice)\n\nasyncio.run(insert_alice())\n\n```\n\nORM Layer\n=========\n\n```python\nimport asyncio\nfrom aiogcd.connector import GcdConnector\nfrom aiogcd.connector.key import Key\nfrom aiogcd.orm import GcdModel\nfrom aiogcd.orm.properties import StringValue\nfrom aiogcd.orm.properties import IntegerValue\n\n# Create a GcdModel for kind 'User'\nclass User(GcdModel):\n    name = StringValue()\n    age = IntegerValue()\n\n# If you want a model for a specific kind and use a different class name\n# you can set __kind__ to the required kind name. For example:\n\n#  class UserModel(GcdModel):\n#      __kind__ = 'User'\n#      ...\n\n# example insert\nasync def insert_alice():\n    # Create a key. As name/id we are allowed to use None since this is\n    # a new key. Gcd will assign a new id to the key.\n    key = Key('User', None, project_id=gcd.project_id)\n\n    # Create a new User entity.\n    alice = User(name='Alice', age=26, key=key)\n\n    # note that the key has no id assigned yet.\n    assert alice.key.id is None\n\n    # Insert the new entity.\n    await gcd.insert_entity(alice)\n\n    # The key now has an id assigned\n    assert isinstance(alice.key.id, int)\n\n    # return the key, we can use this later\n    return alice.key\n\n# example query\nasync def query_users():\n    # query all user entities:\n    users = await User.filter().get_entities(gcd)\n\n    # create a Key from a key string:\n    key = Key(ks='\u003ckey_string\u003e')\n\n    # use the Key to get the User entity:\n    user = await User.filter(key=key).get_entity(gcd)\n\n    # get all user entities with name 'Bob' and age greater than 3\n    users = await User.filter(\n        User.name == 'Bob',\n        User.age \u003e 3).get_entities(gcd)\n\n    # get all user entities with name 'Alice' and an ancestor key\n    users = await User.filter(\n        User.name == 'Alice',\n        has_ancestor= Key('Foo', 123)).get_entities(gcd)\n\n    # get all user entities with name 'Alice' and sort on age\n    users = await User.filter(\n        User.name == 'Alice'\n        ).order_by(\n            User.age.ascending\n        ).get_entities(gcd)\n\n    # get first 2 user entities with name 'Alice' and sort on age\n    users = await User.filter(\n        User.name == 'Alice'\n        ).order_by(\n            User.age.ascending\n        ).limit(2).get_entities(gcd)\n\n# example update\nasync def update_age(ks, new_age):\n    # get the user by key string\n    user = await User.filter(key=Key(ks=ks)).get_entity(gcd)\n\n    # change the age\n    user.age = new_age\n\n    # save the changes\n    await gcd.update_entity(user)\n\n\ngcd = GcdConnector(\n    project_id='my_project_id_or_app_id',\n    client_id='my_client_id',\n    client_secret='my_client_secret',\n    token_file='token_file.json')\n\nasyncio.run(gcd.connect())\nasyncio.run(insert_alice())\nasyncio.run(query_users())\n```\n\n\nNamespaces\n==========\n\nAs of version 0.11.4, aiogcd has support for namespaces. For using namespaces the `Key` and `GcdModel`\n\n### Key\n\nWhen initializing a key from a *key-string*, the `namespace_id` is automatically unpacked.\nIf instead a `path` is used, the namespace can be given using the `namespace_id=\u003cmy_namespace\u003e` keyword argument.\n\nIt is also possible to set the namespace using a dictionary, like in the example below:\n\n```json\n{\n    \"partitionId\": {\n        \"projectId\": \"my-project-id\",\n        \"namespaceId\": \"my-namespace\"\n    }\n    ...\n}\n```\n\n### GcdModel\n\nIf a `GcdModel` is used, it is possible to set the *namespace* on the model. For example:\n\n```python\nclass Example(GcdModel):\n    __namespace__ = 'my-namespace'\n```\n\nWith the above solution, queries like `Example.get_entities(gcd)` will automatically query the correct namespace.\n\nAs an alternative, the `GcdConnector` can be initialized using the `namespace_id=...` keyword argument.\nIf the `namespace_id` argument is used, all queries will use the given namespace unless explicitly overwritten by a `GcdModel`.\n\n\nEmulator\n========\n\nThe Google Datastore emulator is supported by `aiogcd` and thus reads the `DATASTORE_EMULATOR_HOST` environment variable.\nNote that the `DATASTORE_PROJECT_ID` will be ignored and still needs to be set using the initialization of the `GcdConnector`.\nSee https://cloud.google.com/datastore/docs/tools/datastore-emulator for documentation on how to start the emulator.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcesbit%2Faiogcd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcesbit%2Faiogcd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcesbit%2Faiogcd/lists"}