Skip to content

Commit 8991456

Browse files
authored
Add section to README on working with the code
1 parent 82a23d6 commit 8991456

File tree

1 file changed

+70
-14
lines changed

1 file changed

+70
-14
lines changed

README.rst

Lines changed: 70 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,27 @@
11
django-postgres-extra
22
---------------------
33

4-
.. image:: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/badges/quality-score.png
5-
:target: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/
4+
================= ===================
5+
**Quality** |QualityBadge|_
6+
**Test coverage** |CoverageBadge|_
7+
**License** |LicenseBadge|_
8+
**PyPi** |PyPiBadge|_
9+
================= ===================
610

7-
.. image:: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/badges/coverage.png
8-
:target: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/
11+
.. |QualityBadge| image:: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/badges/quality-score.png
12+
.. _QualityBadge: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/
913

10-
.. image:: https://img.shields.io/:license-mit-blue.svg
11-
:target: http://doge.mit-license.org
1214

13-
.. image:: https://badge.fury.io/py/django-postgres-extra.svg
14-
:target: https://pypi.python.org/pypi/django-postgres-extra
15+
.. |CoverageBadge| image:: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/badges/coverage.png
16+
.. _CoverageBadge: https://scrutinizer-ci.com/g/SectorLabs/django-postgres-extra/
17+
18+
19+
.. |LicenseBadge| image:: https://img.shields.io/:license-mit-blue.svg
20+
.. _LicenseBadge: http://doge.mit-license.org
21+
22+
23+
.. |PyPiBadge| image:: https://badge.fury.io/py/django-postgres-extra.svg
24+
.. _PyPiBadge: https://pypi.python.org/pypi/django-postgres-extra
1525

1626
``django-postgres-extra`` aims to make all of PostgreSQL's awesome features available through the Django ORM. We do this by taking care of all the hassle. As opposed to the many small packages that are available to try to bring a single feature to Django with minimal effort. ``django-postgres-extra`` goes the extra mile, with well tested implementations, seamless migrations and much more.
1727

@@ -21,6 +31,7 @@ With seamless we mean that any features we add will work truly seamlessly. You s
2131

2232
Major features
2333
--------------
34+
2435
* Native upserts
2536
* Single query
2637
* Concurrency safe
@@ -49,15 +60,16 @@ Desired/future features
4960

5061
Installation
5162
------------
63+
5264
1. Install the package from PyPi:
5365

5466
.. code-block:: bash
5567
56-
$ pip install django-postgres-extra
68+
λ pip install django-postgres-extra
5769
5870
2. Add ``postgres_extra`` and ``django.contrib.postgres`` to your ``INSTALLED_APPS``:
5971

60-
.. code-block:: bash
72+
.. code-block:: python
6173
6274
INSTALLED_APPS = [
6375
....
@@ -85,16 +97,60 @@ FAQ - Frequently asked questions
8597

8698
1. Why do I need to change the database back-end/engine?
8799

88-
We utilize PostgreSQL's `hstore` data type, which allows you to store key-value pairs in a column. In order to create `UNIQUE` constraints on specific key, we need to create a special type of index. We could do this without a custom database back-end, but it would require everyone to manually write their migrations. By using a custom database back-end, we added support for this. When changing the `uniqueness` constraint on a `HStoreField`, our custom database back-end takes care of creating, updating and deleting these constraints/indexes in the database.
100+
We utilize PostgreSQL's `hstore` data type, which allows you to store key-value pairs in a column. In order to create `UNIQUE` constraints on specific key, we need to create a special type of index. We could do this without a custom database back-end, but it would require everyone to manually write their migrations. By using a custom database back-end, we added support for this. When changing the `uniqueness` constraint on a `HStoreField`, our custom database back-end takes care of creating, updating and deleting these constraints/indexes in the database.
89101

90102
2. I am already using a custom database back-end, can I still use yours?
91103

92-
Yes. You can set the ``POSTGRES_EXTRA_DB_BACKEND_BASE`` setting to your current back-end. This will instruct our custom database back-end to inherit from the database back-end you specified. **Warning**: this will only work if the base you specified indirectly inherits from the standard PostgreSQL database back-end.
104+
Yes. You can set the ``POSTGRES_EXTRA_DB_BACKEND_BASE`` setting to your current back-end. This will instruct our custom database back-end to inherit from the database back-end you specified. **Warning**: this will only work if the base you specified indirectly inherits from the standard PostgreSQL database back-end.
93105

94106
3. Does this package work with Python 2?
95107

96-
No. Only Python 3.5 or newer is supported. We're using type hints. These do not work well under older versions of Python.
108+
No. Only Python 3.5 or newer is supported. We're using type hints. These do not work well under older versions of Python.
97109

98110
4. Does this package work with Django 1.X?
99111

100-
No. Only Django 1.10 or newer is supported.
112+
No. Only Django 1.10 or newer is supported.
113+
114+
115+
Working with the code
116+
----------
117+
118+
**Prerequisites**
119+
120+
* PostgreSQL 9.6 or newer.
121+
* Django 1.10 or newer.
122+
* Python 3.5 or newer.
123+
124+
**Getting started**
125+
126+
1. Clone the repository:
127+
128+
.. code-block:: bash
129+
130+
λ git clone https://github.com/SectorLabs/django-postgres-extra.git
131+
132+
2. Create a virtual environment:
133+
134+
.. code-block:: bash
135+
136+
λ cd django-postgres-extra
137+
λ virtualenv env
138+
λ source env/bin/activate
139+
140+
3. Install the development/test dependencies:
141+
142+
.. code-block:: bash
143+
144+
λ pip install -r requirements/test.txt
145+
146+
4. Run the tests:
147+
148+
.. code-block:: bash
149+
150+
λ py.test
151+
152+
5. Run the benchmarks:
153+
154+
.. code-block:: bash
155+
156+
λ py.test -c pytest-benchmark.ini

0 commit comments

Comments
 (0)