README.rst
1
2Python 3 interface to decode and encode GRIB and BUFR files via the
3`ECMWF ecCodes library <https://software.ecmwf.int/wiki/display/ECC/>`_.
4
5Features:
6
7- reads and writes GRIB 1 and 2 files,
8- reads and writes BUFR 3 and 4 files,
9- supports all modern versions of Python 3.8, 3.7, 3.6, 3.5 and PyPy3,
10- works on most *Linux* distributions and *MacOS*, the *ecCodes* C-library
11- is the only system dependency,
12- PyPI package can be installed without compiling,
13 at the cost of being twice as slow as the original *ecCodes* module,
14- an optional compile step makes the code as fast as the original module
15 but it needs the recommended (the most up-to-date) version of *ecCodes*.
16
17Limitations:
18
19- Microsoft Windows support is untested.
20
21
22Installation
23============
24
25The package is installed from PyPI with::
26
27 $ pip install eccodes
28
29
30System dependencies
31-------------------
32
33The Python module depends on the ECMWF *ecCodes* library
34that must be installed on the system and accessible as a shared library.
35
36On a MacOS with HomeBrew use::
37
38 $ brew install eccodes
39
40Or if you manage binary packages with *Conda* use::
41
42 $ conda install -c conda-forge eccodes
43
44As an alternative you may install the official source distribution
45by following the instructions at
46https://software.ecmwf.int/wiki/display/ECC/ecCodes+installation
47
48You may run a simple selfcheck command to ensure that your system is set up correctly::
49
50 $ python -m eccodes selfcheck
51 Found: ecCodes v2.21.0.
52 Your system is ready.
53
54
55Usage
56-----
57
58Refer to the *ecCodes* `documentation pages <https://confluence.ecmwf.int/display/ECC/Documentation>`_
59for usage.
60
61
62Experimental features
63=====================
64
65Fast bindings
66-------------
67
68To test the much faster *CFFI* API level, out-of-line mode you need the
69*ecCodes* header files.
70Then you need to clone the repo in the same folder as your *ecCodes*
71source tree, make a ``pip`` development install and custom compile
72the binary bindings::
73
74 $ git clone https://github.com/ecmwf/eccodes-python
75 $ cd eccodes-python
76 $ pip install -e .
77 $ python builder.py
78
79To revert back to ABI level, in-line more just remove the compiled bindings::
80
81 $ rm gribapi/_bindings.*
82
83
84Project resources
85=================
86
87============= =========================================================
88Development https://github.com/ecmwf/eccodes-python
89Download https://pypi.org/project/eccodes
90============= =========================================================
91
92
93Contributing
94============
95
96The main repository is hosted on GitHub,
97testing, bug reports and contributions are highly welcomed and appreciated:
98
99https://github.com/ecmwf/eccodes-python
100
101Please see the CONTRIBUTING.rst document for the best way to help.
102
103Maintainer:
104
105- `Shahram Najm <https://github.com/shahramn>`_ - `ECMWF <https://ecmwf.int>`_
106
107Contributors:
108
109- `Alessandro Amici <https://github.com/alexamici>`_ - `B-Open <https://bopen.eu>`_
110
111See also the list of `contributors <https://github.com/ecmwf/eccodes-python/contributors>`_
112who participated in this project.
113
114.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN
115
116License
117=======
118
119|copy| Copyright 2017- ECMWF.
120
121This software is licensed under the terms of the Apache Licence Version 2.0
122which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
123
124In applying this licence, ECMWF does not waive the privileges and immunities
125granted to it by virtue of its status as an intergovernmental organisation nor
126does it submit to any jurisdiction.
127