Skip to content

Commit de892fd

Browse files
committed
Update the README.
1 parent 5334388 commit de892fd

File tree

2 files changed

+51
-65
lines changed

2 files changed

+51
-65
lines changed

README.rst

+50-65
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,51 @@
11
|Build Status|
2+
|Appveyor Build|
23
|Documentation Status|
34

45
An efficient and light-weight ordered set of 32 bits integers.
56
This is a Python wrapper for the C library `CRoaring <https://github.com/RoaringBitmap/CRoaring>`__.
67

7-
The wrapping used to be done with ``Ctypes``. We recently switched to
8-
``Cython`` for the following reasons:
8+
Example
9+
-------
910

10-
- Much better performances for short function calls (e.g.
11-
addition/deletion of a single element).
12-
- Easier installation, no need to install manually the C library, it is
13-
now distributed with PyRoaring.
14-
- Extensibility, it will be easier to write efficient codes with Cython
15-
(e.g. some data structures based on roaring bitmaps).
11+
You can use a bitmap nearly as the classical Python set in your code:
1612

17-
If for some reason you wish to keep using the old version, based on
18-
``Ctypes``, use `PyRoaring
19-
0.0.7 <https://github.com/Ezibenroc/PyRoaringBitMap/tree/0.0.7>`__.
13+
.. code:: python
2014
21-
Requirements
22-
------------
15+
from pyroaring import BitMap
16+
bm1 = BitMap()
17+
bm1.add(3)
18+
bm1.add(18)
19+
bm2 = BitMap([3, 27, 42])
20+
print("bm1 = %s" % bm1)
21+
print("bm2 = %s" % bm2)
22+
print("bm1 & bm2 = %s" % (bm1&bm2))
23+
print("bm1 | bm2 = %s" % (bm1|bm2))
2324
24-
- Environment like Linux and MacOS
25-
- Python 2.7, or Python 3.4 or better
26-
- A recent C compiler like GCC
27-
- The package manager ``pip``
28-
- The Python package ``hypothesis`` (optional, for testing)
29-
- The Python package ``Cython`` (optional, for compiling pyroaring from
30-
the sources)
31-
- The Python package ``wheel`` (optional, to build a wheel for the library)
25+
Output:
3226

33-
Installation
34-
------------
27+
::
28+
29+
bm1 = BitMap([3, 18])
30+
bm2 = BitMap([3, 27, 42])
31+
bm1 & bm2 = BitMap([3])
32+
bm1 | bm2 = BitMap([3, 18, 27, 42])
33+
34+
Installation from Pypi
35+
----------------------
36+
37+
Note: this installation method requires a recent C compiler like GCC.
38+
39+
Supported systems:
40+
41+
- Linux and MacOS: Python 2.7 or Python 3.4 or higher.
42+
- Windows: Python 3.4 or higher.
3543

3644
To install pyroaring on your local account, use the following command:
3745

3846
.. code:: bash
3947
40-
pip install pyroaring --user # installs PyRoaringBitMap
48+
pip install pyroaring --user
4149
4250
For a system-wide installation, use the following command:
4351

@@ -51,15 +59,29 @@ the commands by ``sudo``).
5159
If you want to use Python 3 and your system defaults on Python 2.7, you
5260
may need to adjust the above commands, e.g., replace ``pip`` by ``pip3``.
5361

62+
Installation from the wheels
63+
----------------------------
64+
65+
Several wheels are published on GitHub for each release:
66+
https://github.com/Ezibenroc/PyRoaringBitMap/releases
67+
68+
Installing from a wheel should be the easiest as no C compiler is required. However, performance may be lower. Note that
69+
you have to chose the right wheel, depending on your system.
70+
71+
For instance, to install ``pyroaring`` version ``0.2.1`` for Python ``3.6`` on Linux:
72+
73+
.. code:: bash
74+
75+
pip install --user https://github.com/Ezibenroc/PyRoaringBitMap/releases/download/0.2.1/pyroaring-0.2.1-cp36-cp36m-linux_x86_64.whl
76+
5477
Manual compilation / installation
5578
---------------------------------
5679

5780
If you want to compile (and install) pyroaring by yourself, for instance
5881
to modify the Cython sources or because you do not have ``pip``, follow
5982
these steps.
6083

61-
Note that the Python package ``Cython`` is required. You may be able install
62-
it as:
84+
Note that the Python package ``Cython`` is required. You may install it as:
6385

6486
.. code:: bash
6587
@@ -129,45 +151,6 @@ Example of use:
129151
130152
DEBUG=1 ARCHI=x86-64 python setup.py build_ext
131153
132-
Utilization
133-
-----------
134-
135-
First, you can run the tests to make sure everything is ok:
136-
137-
.. code:: bash
138-
139-
pip install hypothesis --user
140-
python test.py
141-
142-
Note: you can define the environment variable ``HYPOTHESIS_PROFILE`` to ``debug`` to print every values,
143-
or ``ci`` to perform more tests (warning: very long). For instance:
144-
145-
.. code:: bash
146-
147-
HYPOTHESIS_PROFILE=debug ./test.py
148-
149-
You can use a bitmap nearly as the classical Python set in your code:
150-
151-
.. code:: python
152-
153-
from pyroaring import BitMap
154-
bm1 = BitMap()
155-
bm1.add(3)
156-
bm1.add(18)
157-
bm2 = BitMap([3, 27, 42])
158-
print("bm1 = %s" % bm1)
159-
print("bm2 = %s" % bm2)
160-
print("bm1 & bm2 = %s" % (bm1&bm2))
161-
print("bm1 | bm2 = %s" % (bm1|bm2))
162-
163-
Output:
164-
165-
::
166-
167-
bm1 = BitMap([3, 18])
168-
bm2 = BitMap([3, 27, 42])
169-
bm1 & bm2 = BitMap([3])
170-
bm1 | bm2 = BitMap([3, 18, 27, 42])
171154
172155
Benchmark
173156
---------
@@ -227,5 +210,7 @@ small slice 8.93e-05 3.00e-01 3.60e-03
227210

228211
.. |Build Status| image:: https://travis-ci.org/Ezibenroc/PyRoaringBitMap.svg?branch=master
229212
:target: https://travis-ci.org/Ezibenroc/PyRoaringBitMap
213+
.. |Appveyor Build| image:: https://ci.appveyor.com/api/projects/status/6hk915xgpvrwhirm?svg=true
214+
:target: https://ci.appveyor.com/project/Ezibenroc/pyroaringbitmap
230215
.. |Documentation Status| image:: https://readthedocs.org/projects/pyroaringbitmap/badge/?version=stable
231216
:target: http://pyroaringbitmap.readthedocs.io/en/stable/?badge=stable

setup.py

+1
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,7 @@ def write_version(filename, version_dict):
117117
'Intended Audience :: Developers',
118118
'Operating System :: POSIX :: Linux',
119119
'Operating System :: MacOS :: MacOS X',
120+
'Operating System :: Microsoft :: Windows',
120121
'Programming Language :: Python :: 2.7',
121122
'Programming Language :: Python :: 3.4',
122123
'Programming Language :: Python :: 3.5',

0 commit comments

Comments
 (0)