{"id":19810985,"url":"https://github.com/accenture/cymple","last_synced_at":"2025-04-05T11:07:56.328Z","repository":{"id":62628348,"uuid":"476320463","full_name":"Accenture/Cymple","owner":"Accenture","description":"Cymple - a productivity tool for creating Cypher queries in Python","archived":false,"fork":false,"pushed_at":"2024-11-06T13:53:04.000Z","size":155,"stargazers_count":53,"open_issues_count":1,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-29T10:05:42.662Z","etag":null,"topics":["cypher","neo4j","nodes-2022","python","query-builder"],"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/Accenture.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-31T13:35:07.000Z","updated_at":"2025-03-12T23:18:49.000Z","dependencies_parsed_at":"2024-07-16T13:55:34.988Z","dependency_job_id":"07a4c286-3bc8-4754-8904-bbc8ca323ab3","html_url":"https://github.com/Accenture/Cymple","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Accenture%2FCymple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Accenture%2FCymple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Accenture%2FCymple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Accenture%2FCymple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Accenture","download_url":"https://codeload.github.com/Accenture/Cymple/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"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":["cypher","neo4j","nodes-2022","python","query-builder"],"created_at":"2024-11-12T09:24:17.095Z","updated_at":"2025-04-05T11:07:56.310Z","avatar_url":"https://github.com/Accenture.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cymple - Cypher Modular Pythonic Language Extension\r\n\r\nA productivity tool for creating Cypher queries in Python.\r\n\r\n[![Documentation Status](https://readthedocs.org/projects/cymple/badge/?version=latest)](https://cymple.readthedocs.io/en/latest/?badge=latest)\r\n[![Python package](https://github.com/Accenture/Cymple/actions/workflows/python-test.yml/badge.svg)](https://github.com/Accenture/Cymple/actions/workflows/python-test.yml)\r\n\r\n## About the project\r\n\r\nCymple is a lightweight Python package for creating queries in Cypher, Neo4j's graph database query language. \r\nGive it a try, it's 'Cymple'!\r\n\r\nConsider using Cymple if you want:\r\n* auto-completion for writing Cypher\r\n* to write compound Cypher queries without getting involved with strings\r\n* to write Cypher queries in a scalable and extensible manner\r\n* to be able to easily reuse Cypher queries across your code\r\n\r\n![image](https://user-images.githubusercontent.com/97434370/162214862-2cd00d28-0565-4838-af41-9e0c0f49b090.png)\r\n\r\n\r\n## Getting Started\r\n\r\n### Setup\r\n```shell\r\npip install cymple\r\n```\r\n\r\n### Examples\r\n\r\n#### Simple Example\r\nLet's take a look at the following snippet. \r\n```python\r\nfrom cymple import QueryBuilder\r\n\r\nqb = QueryBuilder()\r\nquery = qb.match().node(labels='Person', ref_name='p')\r\nquery = query.where('p.name', '=', '\"Michelle\"').return_literal('p')\r\nprint(query)\r\n```\r\nThis snippet will output the following Cypher query:\r\n```cypher\r\nMATCH (p: Person) WHERE p.name = \"Michelle\" RETURN p\r\n```\r\n\r\nSee the `samples` directory for examples. \r\n\r\n##### Cymple is intended for creating Cypher queries in Python, rather than executing queries on an actual DB. \r\n##### For executing queries, see [Neo4j's Bolt driver for Python](https://github.com/neo4j/neo4j-python-driver). See also `neo4j_e2e.py` in the `samples` directory. \r\n\r\n\r\n#### Autocompletion\r\nCymple is designed to provide autocompletion on IDEs that support autocompletion. This feature is context aware with respect to the current query being written. \r\n\r\n\r\n![gif1](https://user-images.githubusercontent.com/97434370/162214796-cd1eeb70-9875-4a3c-9008-6bcda7fb4896.gif)\r\n\r\n\r\n#### Reusing Queries\r\nTwo queries can be combined to a create a new one. \r\n```python\r\nqb = QueryBuilder()\r\nquery1 = qb.match().node(labels='Person', ref_name='p').with_('p')\r\nquery2 = qb.match().node(labels='Person', ref_name='q').related_to('friend_of').node(ref_name='p')\r\nquery = query1 + query2\r\nprint(query)\r\n```\r\nThis snippet will output the following Cypher query:\r\n```cypher\r\nMATCH (p: Person) WITH p MATCH (q: Person)-[: friend_of]-\u003e(p)\r\n```\r\n\r\n### Prerequisites\r\n\r\n* Python 3.8+\r\n\r\n## Contributing\r\n\r\n### Intro\r\nWe encourage you to help us to improve this package! \r\nThese instructions will give you a copy of the project up and running on your local machine for development and testing purposes.\r\n\r\n### Installing a Development Environment\r\n\r\n```shell\r\n\r\n# Set virtual environment.\r\npython -m venv .venv\r\nsource .venv/bin/activate\r\n\r\n# Upgrade pip\r\n\r\n# Install development dependencies.\r\n# Tools needed for deployment and packaging will be installed now.\r\n\r\npip install -r requirements-dev.txt\r\n```\r\n\r\n### Development tools configurations\r\n\r\n* `setuptools` is configured in `setup.cfg`\r\n\r\n* `pycodestyle` is configured in `setup.cfg`\r\n\r\n* `coverage.py` is configured in `pyproject.toml` \r\n\r\n\r\n### Testing\r\n\r\n`pytest` is used as a test runner.\r\n\r\n`pytest` configurations reside in `pyproject.toml`\r\n\r\n`pytest` `fixtures` are stored in `tests/conftest.py` file.\r\n\r\nHow-to run tests:\r\n\r\n```shell\r\n# Install test requirements.\r\n\r\npip install -r requirements-test.txt\r\n\r\n# Run tests.\r\n# All the tests under tests/ directory will be run.\r\n\r\npytest --cov=cymple\r\n\r\n```\r\n\r\n### Adding a new Cypher clause\r\nAdding a new Cypher clause to Cymple consists of few simple steps:\r\n1. Go to `src/cymple/internal/declarations/`. This directory contains all supported clause declarations. \r\n2. Add a json file describing the clause and the method(s) interfaces(s) of the new clause that you would like to add to the builder. If you do it for the first time, take a look at existing json files of currently supported Cypher clauses.\r\n3. Identify all the existing clauses that can precede your new clause, and add your new clause's name to the 'successors' list of those clauses' JSONs.\r\n4. Run `python src/cymple/internal/internal_renderer.py`. This script generates a new `builder.py` file with all clauses that were declared in `src/cymple/internal/declarations/`. \r\n5. By default, by adding a declaration json file, the `internal_builder.py` script takes the declared clause and generates a method that simply concatenates your new clause to the builder's current query. However, if you need anything more complex than that, you can write your own implementation by creating a new method with your clause's name at `src/cymple/internal/overloads/`. Don't forget to run `python src/cymple/internal/internal_renderer.py` again :)\r\n6. If you're satisfied with the new clause, add a unit test in `test_clauses.py` and make sure it generates the expected Cypher string. \r\n\r\n### Generating Documentation\r\n\r\nMake sure you run:\r\n```\r\npip install -r requirements-dev.txt\r\n```\r\nor\r\n```\r\npip install sphinx\r\n```\r\nto proceed.\r\n\r\nTo generate a new HTML documentation, run:\r\n```\r\ncd docs\r\nmake clean html\r\nmake html\r\n```\r\n\r\n### Versioning\r\n\r\n[Semantic Versioning](http://semver.org/) is used for versioning. \r\n\r\nFor the versions available, see the tags on the repository.\r\n\r\nCurrent version is stored in `src/cymple/version.py`.\r\n\r\n\r\n### Project structure\r\n\r\n```shell\r\ncymple/\r\n├── docs/   # Project documentation\r\n├── pyproject.toml  # Development and packaging tools configurations\r\n├── README.md  # Project general information\r\n├── requirements-dev.txt  # Development dependencies, such as packaging tools, etc.\r\n├── requirements-test.txt  # Test dependencies\r\n├── requirements.txt       # Pinned versions of all the end-user dependency tree\r\n├── setup.cfg  # packaging tool configurations\r\n├── setup.py   # Packaging script\r\n├── src/  # All source code\r\n│   └── cymple/  # Cymple source code\r\n│       ├── internal/  # Cypher builder internal renderer\r\n│       │   ├── declarations/        # clause declarations\r\n│       │   ├── overloads/           # custom clause implementations\r\n│       │   ├── finale.py            # A part of the rendered code that comes last\r\n│       │   ├── internal_renderer.py # Internal renderer implementation for creating Cymple's user-facing code\r\n│       │   └── preface.py           # A part of the rendered code that comes first\r\n│       ├── __init__.py  # Package initialization\r\n│       ├── __main__.py  # Main script when run as a command line tool\r\n│       ├── builder.py   # Query Builder implementation\r\n│       ├── typedefs.py  # Query Builder typedefs to be used in Cymple's API\r\n│       └── version.py   # Package version\r\n└── tests/  # Tests\r\n    ├── conftest.py  # Fixtures\r\n    ├── data/  # Tests data files, such as input/output files, mocks, etc.\r\n    ├── e2e/   # End-to-End functional tests\r\n    ├── integration  # Integration tests\r\n    └── unit  # Unit tests\r\n        ├── __init__.py\r\n        └── test_real_use_cases.py  # Test project startup\r\n\r\n\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccenture%2Fcymple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faccenture%2Fcymple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccenture%2Fcymple/lists"}