{"id":13542345,"url":"https://github.com/adewes/blitzdb","last_synced_at":"2025-04-04T17:05:46.037Z","repository":{"id":14144098,"uuid":"16849748","full_name":"adewes/blitzdb","owner":"adewes","description":"Blitz is a document-oriented database for Python that is backend-agnostic. It comes with a flat-file database for JSON documents and provides MongoDB-like querying capabilities.","archived":false,"fork":false,"pushed_at":"2021-07-12T10:05:07.000Z","size":1178,"stargazers_count":330,"open_issues_count":26,"forks_count":37,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-03-28T16:11:14.799Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://blitzdb.readthedocs.org","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/adewes.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}},"created_at":"2014-02-14T21:18:44.000Z","updated_at":"2025-02-16T16:44:54.000Z","dependencies_parsed_at":"2022-08-27T19:10:13.008Z","dependency_job_id":null,"html_url":"https://github.com/adewes/blitzdb","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adewes%2Fblitzdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adewes%2Fblitzdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adewes%2Fblitzdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adewes%2Fblitzdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adewes","download_url":"https://codeload.github.com/adewes/blitzdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217175,"owners_count":20903008,"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":[],"created_at":"2024-08-01T10:01:05.189Z","updated_at":"2025-04-04T17:05:46.007Z","avatar_url":"https://github.com/adewes.png","language":"Python","readme":"# Blitz-DB\n\n[![Build Status](https://travis-ci.org/adewes/blitzdb.svg?branch=master)](https://travis-ci.org/adewes/blitzdb)\n[![PyPI](https://img.shields.io/pypi/v/blitzdb.svg?maxAge=1000)](https://pypi.python.org/pypi/blitzdb)\n[![Code Issues](http://www.quantifiedcode.com/api/v1/project/gh:adewes:blitzdb/badge.svg)](http://www.quantifiedcode.com/app/project/gh:adewes:blitzdb)\n[![Python 3](http://img.shields.io/badge/Python%203%20-compatible-brightgreen.svg)](https://www.python.org/download/releases/3.0/)\n\n**BlitzDB**, or just **Blitz** is a document-based, object-oriented, transactional database written purely in Python. Among other things, it provides a **powerful querying language**, **deep indexing of documents**, **compressed data storage** and **automatic referencing of embedded documents**. It is reasonably fast, can be easily embedded in any Python application and does not have any external dependencies (except when using a third-party backend). In addition, you can use it as a **frontend** to other database engines such as MongoDB in case you should need more power.\n\n## [Go To Main Documentation](http://blitzdb.readthedocs.org)\n\n## Key Features\n\n* Document-based, object-oriented interface.\n* Powerful and rich querying language.\n* Deep document indexes on arbitrary fields.\n* Compressed storage of documents.\n* Support for multiple backends (e.g. file-based storage, MongoDB).\n* Support for database transactions (currently only for the file-based backend).\n\n## Use Cases\n\nBlitz can be used as a standalone document store for client application. Originally blitz was designed for use with the [checkmate](https://github.com/quantifiedcode/checkmate) Python code analysis toolkit, where it stores statistical data. Since blitz stores all documents as single JSON files, it is possible to put the whole database under version-control.\n\n## Installation\n\nThe easiest way to install Blitz is through **pip** or **easy_install**\n\n    pip install blitzdb\n    #or...\n    easy_install blitzdb\n\nFor more detailed installation instructions, have a look at the [documentation](http://blitzdb.readthedocs.org).\n\n## Detailed Documentation\n\nThe detailed documentation for this project is hosted on [ReadTheDocs](http://blitzdb.readthedocs.org), feel free to take a look!\n\n## Changelog\n\n* 0.4.4: SQL backend: Do not coerce server_default values via a CAST, as this can cause incompatibilities.\n* 0.4.3: Many small improvements to the SQL backend.\n* 0.3.0: Fully functional SQL backend.\n* 0.2.12: Added support for proper attribute iteration to `Document`.\n* 0.2.11: Allow setting the `collection` parameter through a `Document.Meta` attribute.\n* 0.2.10: Bugfix-Release: Fix Python 3 compatibility issue.\n* 0.2.9: Bugfix-Release: Fix serialization problem with file backend.\n* 0.2.8: Added `get`, `has_key` and `clear` methods to `Document` class\n* 0.2.7: Fixed problem with __unicode__ function in Python 3.\n* 0.2.6: Bugfix-Release: Fixed an issue with the $exists operator for the file backend.\n* 0.2.5: Bugfix-Release\n* 0.2.4: Added support for projections and update operations to the MongoDB backend.\n* 0.2.3: Bugfix-Release: Fixed bug in transaction data caching in MongoDB backend.\n* 0.2.2: Fix for slice operators in MongoDB backend.\n* 0.2.1: Better tests.\n* 0.2.0: Support for including additional information in DB references. Support for accessing document attributes as dictionary items.\n         Added $regex parameter that allows to use regular expressions in queries.\n* 0.1.5: MongoDB backend now supports database transactions. Database operations are now read-isolated by default, i.e.\n         uncommitted operations will not affect database queries before they are committed.\n* 0.1.4: Improved indexing of objects for the file backend, added support for automatic serialization/deserialization\n         of object attributes when adding keys to or querying an index.\n* 0.1.3: Sorting of query sets is now supported (still experimental)\n* 0.1.2: Small bugfixes, BlitzDB version number now contained in DB config dict\n* 0.1.1: BlitzDB is now Python3 compatible (thanks to David Koblas)\n\n## Contributors (in alphabetical order)\n\n*  @bwiessneth\n*  Florian Lehmann - @cashaddy\n*  Karskrin - @cBrauge\n*  Chris Mutel - @cmutel\n*  Cecil Woebker - @cwoebker\n*  Ethan Blackburn - @EthanBlackburn\n*  Javier Collado - @jcollado\n*  Jason Xie - @jxieeducation\n*  David Koblas - @koblas\n*  Stéphane Wirtel - @matrixise\n*  Victor Miclovich - @miclovich\n*  Dmytro Kyrychuk - @orgkhnargh\n*  Christoph Neumann - @programmdesign\n*  Dale - @puredistortion\n*  tjado - @tejado\n*  Thomas Ballinger - @thomasballinger\n*  Tyler Kennedy - @TkTech\n*  Toby Champion - @tobych\n\nThanks for all your contributions, without you BlitzDB wouldn't be what it is today :)\n\n## Third-Party Contributions\n\n* [Flask-BlitzDB](https://github.com/puredistortion/flask-blitzdb) Flask adapter for BlitzDB. Blitz + Flask = Awesome!\n\n## Examples\n\nTo get an idea of what you can do with Blitz, here are some examples.\n\n### Creating objects\n\n```python\nfrom blitzdb import Document\n\nclass Movie(Document):\n    pass\n\nclass Actor(Document):\n    pass\n\nthe_godfather = Movie({'name': 'The Godfather','year':1972,'pk':1L})\n\nmarlon_brando = Actor({'name':'Marlon Brando','pk':1L})\nal_pacino = Actor({'name' : 'Al Pacino','pk':1L})\n```\n\n### Storing objects in the database:\n\n```python\nfrom blitzdb import FileBackend\n\nbackend = FileBackend(\"/path/to/my/db\")\n\nthe_godfather.save(backend)\nmarlon_brando.save(backend)\nal_pacino.save(backend)\n```\n\n### Retrieving objects from the database:\n\n```python\nthe_godfather = backend.get(Movie,{'pk':1L})\n#or...\nthe_godfather = backend.get(Movie,{'name' : 'The Godfather'})\n```\n\n### Filtering objects\n\n```python\nmovies_from_1972 = backend.filter(Movie,{'year' : 1972})\n```\n\n### Working with transactions\n\n```python\nbackend.begin()\nthe_godfather.director = 'Roland Emmerich' #oops...\nthe_godfather.save()\nbackend.rollback() #undo the changes...\n```\n\n### Creating nested object references\n\n```python\nthe_godfather.cast = {'Don Vito Corleone' : marlon_brando, 'Michael Corleone' : al_pacino}\n\n#Documents stored within other objects will be automatically converted to database references.\n\nmarlon_brando.performances = [the_godfather]\nal_pacino.performances = [the_godfather]\n\nmarlon_brando.save(backend)\nal_pacino.save(backend)\nthe_godfather.save(backend)\n#Will store references to the movies within the documents in the DB\n```\n\n### Creation of database indexes and advanced querying\n\n```python\nbackend.create_index(Actor,'performances')\n#Will create an index on the 'performances' field, for fast querying\n\ngodfather_cast = backend.filter(Actor,{'movies' : the_godfather})\n#Will return 'Al Pacino' and 'Marlon Brando'\n```\n\n### Arbitrary filter expressions\n\n```python\nstar_wars_iv = Movie({'name' : 'Star Wars - Episode IV: A New Hope','year': 1977})\nstar_wars_iv.save()\n\nmovies_from_the_seventies = backend.filter(Movie,{'year': lambda year : year \u003e= 1970 and year \u003c 1980})\n#Will return Star Wars \u0026 The Godfather (man, what a decade!)\n```\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadewes%2Fblitzdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadewes%2Fblitzdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadewes%2Fblitzdb/lists"}