Records: SQL for Humans™
========================
.. image:: https://img.shields.io/pypi/v/records.svg
:target: https://pypi.python.org/pypi/records
**Records is a very simple, but powerful, library for making raw SQL queries
to most relational databases.**
.. image:: https://farm1.staticflickr.com/569/33085227621_7e8da49b90_k_d.jpg
Just write SQL. No bells, no whistles. This common task can be
surprisingly difficult with the standard tools available.
This library strives to make this workflow as simple as possible,
while providing an elegant interface to work with your query results.
*Database support includes RedShift, Postgres, MySQL, SQLite, Oracle, and MS-SQL (drivers not included).*
☤ The Basics
------------
We know how to write SQL, so let's send some to our database:
.. code:: python
import records
db = records.Database('postgres://...')
rows = db.query('select * from active_users') # or db.query_file('sqls/active-users.sql')
Grab one row at a time:
.. code:: python
>>> rows[0]
<Record {"username": "model-t", "active": true, "name": "Henry Ford", "user_email": "model-t@gmail.com", "timezone": "2016-02-06 22:28:23.894202"}>
Or iterate over them:
.. code:: python
for r in rows:
print(r.name, r.user_email)
Values can be accessed many ways: ``row.user_email``, ``row['user_email']``, or ``row[3]``.
Fields with non-alphanumeric characters (like spaces) are also fully supported.
Or store a copy of your record collection for later reference:
.. code:: python
>>> rows.all()
[<Record {"username": ...}>, <Record {"username": ...}>, <Record {"username": ...}>, ...]
If you're only expecting one result:
.. code:: python
>>> rows.first()
<Record {"username": ...}>
Other options include ``rows.as_dict()`` and ``rows.as_dict(ordered=True)``.
☤ Features
----------
- Iterated rows are cached for future reference.
- ``$DATABASE_URL`` environment variable support.
- Convenience ``Database.get_table_names`` method.
- Command-line `records` tool for exporting queries.
- Safe parameterization: ``Database.query('life=:everything', everything=42)``.
- Queries can be passed as strings or filenames, parameters supported.
- Transactions: ``t = Database.transaction(); t.commit()``.
- Bulk actions: ``Database.bulk_query()`` & ``Database.bulk_query_file()``.
Records is proudly powered by `SQLAlchemy <http://www.sqlalchemy.org>`_
and `Tablib <https://tablib.readthedocs.io/en/latest/>`_.
☤ Data Export Functionality
---------------------------
Records also features full Tablib integration, and allows you to export
your results to CSV, XLS, JSON, HTML Tables, YAML, or Pandas DataFrames with a single line of code.
Excellent for sharing data with friends, or generating reports.
.. code:: pycon
>>> print(rows.dataset)
username|active|name |user_email |timezone
--------|------|----------|-----------------|--------------------------
model-t |True |Henry Ford|model-t@gmail.com|2016-02-06 22:28:23.894202
...
**Comma Separated Values (CSV)**
.. code:: pycon
>>> print(rows.export('csv'))
username,active,name,user_email,timezone
model-t,True,Henry Ford,model-t@gmail.com,2016-02-06 22:28:23.894202
...
**YAML Ain't Markup Language (YAML)**
.. code:: python
>>> print(rows.export('yaml'))
- {active: true, name: Henry Ford, timezone: '2016-02-06 22:28:23.894202', user_email: model-t@gmail.com, username: model-t}
...
**JavaScript Object Notation (JSON)**
.. code:: python
>>> print(rows.export('json'))
[{"username": "model-t", "active": true, "name": "Henry Ford", "user_email": "model-t@gmail.com", "timezone": "2016-02-06 22:28:23.894202"}, ...]
**Microsoft Excel (xls, xlsx)**
.. code:: python
with open('report.xls', 'wb') as f:
f.write(rows.export('xls'))
**Pandas DataFrame**
.. code:: python
>>> rows.export('df')
username active name user_email timezone
0 model-t True Henry Ford model-t@gmail.com 2016-02-06 22:28:23.894202
You get the point. All other features of Tablib are also available,
so you can sort results, add/remove columns/rows, remove duplicates,
transpose the table, add separators, slice data by column, and more.
See the `Tablib Documentation <https://tablib.readthedocs.io/>`_ for more details.
☤ Installation
--------------
Of course, the recommended installation method is `pipenv <http://pipenv.org>`_::
$ pipenv install records[pandas]
✨🍰✨
☤ Thank You
-----------
Thanks for checking this library out! I hope you find it useful.
Of course, there's always room for improvement. Feel free to `open an issue <https://github.com/kennethreitz/records/issues>`_ so we can make Records better, stronger, faster.
v0.6.0 (04-29-2024)
===================
- Support for Python 3.6+ only.
- Support for SQLAlchemy 2+.
- Dropped support for Python 2.7 and 3.4, with the move to SQLAlchemy 2+.
v0.5.1 (09-01-2017)
===================
- Depend on ``tablib[pandas]``.
- Support for Bulk quies: ``Database.bulk_query()`` & ``Database.bulk_query_file()``.
v0.5.0 (11-15-2016)
===================
- Support for transactions: ``t = Database.transaction(); t.commit()``
v0.4.3 (02-16-2016)
===================
- The cake is a lie.
v0.4.2 (02-15-2016)
===================
- Packaging fix.
v0.4.1 (02-15-2016)
===================
- Bugfix for Python 3.
v0.4.0 (02-13-2016)
===================
- Refactored to be fully powered by SQLAlchemy!
- Support for all major databases (thanks, SQLAlchemy!).
- Support for non-alphanumeric column names.
- New ``Record`` class, for representing/accessing result rows.
- ``ResultSet`` renamed ``RecordCollection``.
- Removed Interactive Mode from the CLI.
v0.3.0 (02-11-2016)
===================
- New ``record`` command-line tool available!
- Various improvements.
v0.2.0 (02-10-2016)
===================
- Results are now represented as `Record`, a namedtuples class with dict-like qualities.
- New `ResultSet.export` method, for exporting to various formats.
- Slicing a `ResultSet` now works, and results in a new `ResultSet`.
- Lots of bugfixes and improvements!
v0.1.0 (02-07-2016)
===================
- Initial release.
Raw data
{
"_id": null,
"home_page": "https://github.com/kennethreitz/records",
"name": "records",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Kenneth Reitz",
"author_email": "me@kennethreitz.org",
"download_url": "https://files.pythonhosted.org/packages/ff/8f/93d4cf7f9d4a5719b582287ca378d028927be2de997c17f830d193c7c27e/records-0.6.0.tar.gz",
"platform": null,
"description": "Records: SQL for Humans\u2122\n========================\n\n\n.. image:: https://img.shields.io/pypi/v/records.svg\n :target: https://pypi.python.org/pypi/records\n\n\n**Records is a very simple, but powerful, library for making raw SQL queries\nto most relational databases.**\n\n.. image:: https://farm1.staticflickr.com/569/33085227621_7e8da49b90_k_d.jpg\n\nJust write SQL. No bells, no whistles. This common task can be\nsurprisingly difficult with the standard tools available.\nThis library strives to make this workflow as simple as possible,\nwhile providing an elegant interface to work with your query results.\n\n*Database support includes RedShift, Postgres, MySQL, SQLite, Oracle, and MS-SQL (drivers not included).*\n\n\u2624 The Basics\n------------\n\nWe know how to write SQL, so let's send some to our database:\n\n.. code:: python\n\n import records\n\n db = records.Database('postgres://...')\n rows = db.query('select * from active_users') # or db.query_file('sqls/active-users.sql')\n\n\nGrab one row at a time:\n\n.. code:: python\n\n >>> rows[0]\n <Record {\"username\": \"model-t\", \"active\": true, \"name\": \"Henry Ford\", \"user_email\": \"model-t@gmail.com\", \"timezone\": \"2016-02-06 22:28:23.894202\"}>\n\nOr iterate over them:\n\n.. code:: python\n\n for r in rows:\n print(r.name, r.user_email)\n\nValues can be accessed many ways: ``row.user_email``, ``row['user_email']``, or ``row[3]``.\n\nFields with non-alphanumeric characters (like spaces) are also fully supported.\n\nOr store a copy of your record collection for later reference:\n\n.. code:: python\n\n >>> rows.all()\n [<Record {\"username\": ...}>, <Record {\"username\": ...}>, <Record {\"username\": ...}>, ...]\n\nIf you're only expecting one result:\n\n.. code:: python\n\n >>> rows.first()\n <Record {\"username\": ...}>\n\nOther options include ``rows.as_dict()`` and ``rows.as_dict(ordered=True)``.\n\n\u2624 Features\n----------\n\n- Iterated rows are cached for future reference.\n- ``$DATABASE_URL`` environment variable support.\n- Convenience ``Database.get_table_names`` method.\n- Command-line `records` tool for exporting queries.\n- Safe parameterization: ``Database.query('life=:everything', everything=42)``.\n- Queries can be passed as strings or filenames, parameters supported.\n- Transactions: ``t = Database.transaction(); t.commit()``.\n- Bulk actions: ``Database.bulk_query()`` & ``Database.bulk_query_file()``.\n\nRecords is proudly powered by `SQLAlchemy <http://www.sqlalchemy.org>`_\nand `Tablib <https://tablib.readthedocs.io/en/latest/>`_.\n\n\u2624 Data Export Functionality\n---------------------------\n\nRecords also features full Tablib integration, and allows you to export\nyour results to CSV, XLS, JSON, HTML Tables, YAML, or Pandas DataFrames with a single line of code.\nExcellent for sharing data with friends, or generating reports.\n\n.. code:: pycon\n\n >>> print(rows.dataset)\n username|active|name |user_email |timezone\n --------|------|----------|-----------------|--------------------------\n model-t |True |Henry Ford|model-t@gmail.com|2016-02-06 22:28:23.894202\n ...\n\n**Comma Separated Values (CSV)**\n\n.. code:: pycon\n\n >>> print(rows.export('csv'))\n username,active,name,user_email,timezone\n model-t,True,Henry Ford,model-t@gmail.com,2016-02-06 22:28:23.894202\n ...\n\n**YAML Ain't Markup Language (YAML)**\n\n.. code:: python\n\n >>> print(rows.export('yaml'))\n - {active: true, name: Henry Ford, timezone: '2016-02-06 22:28:23.894202', user_email: model-t@gmail.com, username: model-t}\n ...\n\n**JavaScript Object Notation (JSON)**\n\n.. code:: python\n\n >>> print(rows.export('json'))\n [{\"username\": \"model-t\", \"active\": true, \"name\": \"Henry Ford\", \"user_email\": \"model-t@gmail.com\", \"timezone\": \"2016-02-06 22:28:23.894202\"}, ...]\n\n**Microsoft Excel (xls, xlsx)**\n\n.. code:: python\n\n with open('report.xls', 'wb') as f:\n f.write(rows.export('xls'))\n \n \n**Pandas DataFrame**\n\n.. code:: python\n\n >>> rows.export('df')\n username active name user_email timezone\n 0 model-t True Henry Ford model-t@gmail.com 2016-02-06 22:28:23.894202\n\nYou get the point. All other features of Tablib are also available,\nso you can sort results, add/remove columns/rows, remove duplicates,\ntranspose the table, add separators, slice data by column, and more.\n\nSee the `Tablib Documentation <https://tablib.readthedocs.io/>`_ for more details.\n\n\u2624 Installation\n--------------\n\nOf course, the recommended installation method is `pipenv <http://pipenv.org>`_::\n\n $ pipenv install records[pandas]\n \u2728\ud83c\udf70\u2728\n\n\u2624 Thank You\n-----------\n\nThanks for checking this library out! I hope you find it useful.\n\nOf course, there's always room for improvement. Feel free to `open an issue <https://github.com/kennethreitz/records/issues>`_ so we can make Records better, stronger, faster.\n\n\n\n\nv0.6.0 (04-29-2024)\n===================\n\n- Support for Python 3.6+ only.\n- Support for SQLAlchemy 2+.\n- Dropped support for Python 2.7 and 3.4, with the move to SQLAlchemy 2+.\n\nv0.5.1 (09-01-2017)\n===================\n\n- Depend on ``tablib[pandas]``.\n- Support for Bulk quies: ``Database.bulk_query()`` & ``Database.bulk_query_file()``.\n\nv0.5.0 (11-15-2016)\n===================\n\n- Support for transactions: ``t = Database.transaction(); t.commit()``\n\n\nv0.4.3 (02-16-2016)\n===================\n\n- The cake is a lie.\n\nv0.4.2 (02-15-2016)\n===================\n\n- Packaging fix.\n\nv0.4.1 (02-15-2016)\n===================\n\n- Bugfix for Python 3.\n\nv0.4.0 (02-13-2016)\n===================\n\n- Refactored to be fully powered by SQLAlchemy!\n- Support for all major databases (thanks, SQLAlchemy!).\n- Support for non-alphanumeric column names.\n- New ``Record`` class, for representing/accessing result rows.\n- ``ResultSet`` renamed ``RecordCollection``.\n- Removed Interactive Mode from the CLI.\n\n\nv0.3.0 (02-11-2016)\n===================\n\n- New ``record`` command-line tool available!\n- Various improvements.\n\nv0.2.0 (02-10-2016)\n===================\n\n- Results are now represented as `Record`, a namedtuples class with dict-like qualities.\n- New `ResultSet.export` method, for exporting to various formats.\n- Slicing a `ResultSet` now works, and results in a new `ResultSet`.\n- Lots of bugfixes and improvements!\n\nv0.1.0 (02-07-2016)\n===================\n\n- Initial release.\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "SQL for Humans",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/kennethreitz/records"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fa9f12ef0f5a187d3f653018f1de03e004570521e574d24a33bd9af27014babf",
"md5": "752e813a7597e550d919b655ba6976fd",
"sha256": "078acc32ef0ebf28e14374e4914cfcc37ec7a9bbbd6eaff9a4a315537cf9465b"
},
"downloads": -1,
"filename": "records-0.6.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "752e813a7597e550d919b655ba6976fd",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 9964,
"upload_time": "2024-03-29T23:50:56",
"upload_time_iso_8601": "2024-03-29T23:50:56.153979Z",
"url": "https://files.pythonhosted.org/packages/fa/9f/12ef0f5a187d3f653018f1de03e004570521e574d24a33bd9af27014babf/records-0.6.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ff8f93d4cf7f9d4a5719b582287ca378d028927be2de997c17f830d193c7c27e",
"md5": "e556921f8ceffc4ef5a6d4cdcdd783e1",
"sha256": "320265b94ae87ca5d22643811aa199ce8a8c50d50064053b1a9a54e6ae565d9f"
},
"downloads": -1,
"filename": "records-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "e556921f8ceffc4ef5a6d4cdcdd783e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12301,
"upload_time": "2024-03-29T23:50:58",
"upload_time_iso_8601": "2024-03-29T23:50:58.350701Z",
"url": "https://files.pythonhosted.org/packages/ff/8f/93d4cf7f9d4a5719b582287ca378d028927be2de997c17f830d193c7c27e/records-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 23:50:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kennethreitz",
"github_project": "records",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "records"
}
JSON
