Package: cymple
Cymple - Cypher Modular Pythonic Language ExtensionA productivity tool for creating Cypher queries in Python.About the projectCymple is a lightweight Python package for creating queries in Cypher, Neo4j's graph database query language.
Give it a try, it's 'Cymple'!Consider using Cymple if you want:auto-completion for writing Cypherto write compound Cypher queries without getting involved with stringsto write Cypher queries in a scalable and extensible mannerto be able to easily reuse Cypher queries across your codeGetting StartedSetuppipinstallcympleExamplesSimple ExampleLet's take a look at the following snippet.fromcympleimportQueryBuilderqb=QueryBuilder()query=qb.match().node(labels='Person',ref_name='p')query=query.where('p.name','=','"Michelle"').return_literal('p')print(query)This snippet will output the following Cypher query:MATCH(p:Person)WHEREp.name="Michelle"RETURNpSee thesamplesdirectory for examples.Cymple is intended for creating Cypher queries in Python, rather than executing queries on an actual DB.For executing queries, seeNeo4j's Bolt driver for Python. See alsoneo4j_e2e.pyin thesamplesdirectory.AutocompletionCymple is designed to provide autocompletion on IDEs that support autocompletion. This feature is context aware with respect to the current query being written.Reusing QueriesTwo queries can be combined to a create a new one.qb=QueryBuilder()query1=qb.match().node(labels='Person',ref_name='p').with_('p')query2=qb.match().node(labels='Person',ref_name='q').related_to('friend_of').node(ref_name='p')query=query1+query2print(query)This snippet will output the following Cypher query:MATCH(p:Person)WITHpMATCH(q:Person)-[:friend_of]->(p)PrerequisitesPython 3.8+ContributingIntroWe encourage you to help us to improve this package!
These instructions will give you a copy of the project up and running on your local machine for development and testing purposes.Installing a Development Environment# Set virtual environment.python-mvenv.venvsource.venv/bin/activate# Upgrade pip# Install development dependencies.# Tools needed for deployment and packaging will be installed now.pipinstall-rrequirements-dev.txtDevelopment tools configurationssetuptoolsis configured insetup.cfgpycodestyleis configured insetup.cfgcoverage.pyis configured inpyproject.tomlTestingpytestis used as a test runner.pytestconfigurations reside inpyproject.tomlpytestfixturesare stored intests/conftest.pyfile.How-to run tests:# Install test requirements.pipinstall-rrequirements-test.txt# Run tests.# All the tests under tests/ directory will be run.pytest--cov=cympleAdding a new Cypher clauseAdding a new Cypher clause to Cymple consists of few simple steps:Go tosrc/cymple/internal/declarations/. This directory contains all supported clause declarations.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.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.Runpython src/cymple/internal/internal_renderer.py. This script generates a newbuilder.pyfile with all clauses that were declared insrc/cymple/internal/declarations/.By default, by adding a declaration json file, theinternal_builder.pyscript 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 atsrc/cymple/internal/overloads/. Don't forget to runpython src/cymple/internal/internal_renderer.pyagain :)If you're satisfied with the new clause, add a unit test intest_clauses.pyand make sure it generates the expected Cypher string.Generating DocumentationMake sure you run:pip install -r requirements-dev.txtorpip install sphinxto proceed.To generate a new HTML documentation, run:cd docs
make clean html
make htmlVersioningSemantic Versioningis used for versioning.For the versions available, see the tags on the repository.Current version is stored insrc/cymple/version.py.Project structurecymple/
├──docs/# Project documentation├──pyproject.toml# Development and packaging tools configurations├──README.md# Project general information├──requirements-dev.txt# Development dependencies, such as packaging tools, etc.├──requirements-test.txt# Test dependencies├──requirements.txt# Pinned versions of all the end-user dependency tree├──setup.cfg# packaging tool configurations├──setup.py# Packaging script├──src/# All source code│└──cymple/# Cymple source code│├──internal/# Cypher builder internal renderer││├──declarations/# clause declarations││├──overloads/# custom clause implementations││├──finale.py# A part of the rendered code that comes last││├──internal_renderer.py# Internal renderer implementation for creating Cymple's user-facing code││└──preface.py# A part of the rendered code that comes first│├──__init__.py# Package initialization│├──__main__.py# Main script when run as a command line tool│├──builder.py# Query Builder implementation│├──typedefs.py# Query Builder typedefs to be used in Cymple's API│└──version.py# Package version└──tests/# Tests├──conftest.py# Fixtures├──data/# Tests data files, such as input/output files, mocks, etc.├──e2e/# End-to-End functional tests├──integration# Integration tests└──unit# Unit tests├──__init__.py└──test_real_use_cases.py# Test project startup