You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 50c808c
Browse filesBrowse the repository at this point in the historyBrowse files
As described in APE4, the version numbers for ``astropy_helpers`` follow the
31
-
corresponding major/minor version of the `astropy core package
32
-
<http://www.astropy.org/>`_, but with an independent sequence of micro (bugfix)
33
-
version numbers. Hence, the initial release is 0.4, in parallel with Astropy
34
-
v0.4, which will be the first version of Astropy to use ``astropy-helpers``.
35
+
As described in `APE4 <https://github.com/astropy/astropy-APEs/blob/master/APE4.rst>`_, the version
36
+
numbers for ``astropy_helpers`` follow the corresponding major/minor version of
37
+
the `astropy core package <http://www.astropy.org/>`_, but with an independent
38
+
sequence of micro (bugfix) version numbers. Hence, the initial release is 0.4,
39
+
in parallel with Astropy v0.4, which will be the first version of Astropy to
40
+
use ``astropy-helpers``.
35
41
36
42
For examples of how to implement ``astropy-helpers`` in a project,
37
43
see the ``setup.py`` and ``setup.cfg`` files of the
where ``NAME`` is the name of your package, ``VERSION`` is the full version
74
+
string, and ``RELEASE`` is a boolean value indicating whether the version is
75
+
a stable released version (``True``) or a developer version (``False``).
76
+
Finally, pass ``cmdclassd`` to the ``setup`` function::
77
+
78
+
setup(...,
79
+
cmdclass=cmdclassd)
80
+
81
+
The commands we provide or customize are:
82
+
83
+
**python setup.py test**
84
+
85
+
This command will automatically build the package, install it to a temporary
86
+
directory, and run the tests using `pytest <http://pytest.org/>`_ on this
87
+
installed version. Note that the bulk of this command is actually defined
88
+
in ``astropy.tests.command.AstropyTest``, because that allows the test
89
+
machinery to operate outside a setuptools command. This, here we
90
+
simply define the custom
91
+
setuptools command.
92
+
93
+
**python setup.py sdist**
94
+
95
+
We redefine ``sdist`` to use the version from distutils rather than from
96
+
setuptools, as the setuptools version requires duplication of information
97
+
in ``MANIFEST.in``.
98
+
99
+
**python setup.py build_docs**
100
+
101
+
This command will automatically build the package, then run sphinx to build
102
+
the documentation. This makes development much easier because it ensures
103
+
sphinx extensions that use the package's code to make documentation are
104
+
actually using the in-development version of the code. Sphinx itself
105
+
provides a custom setuptools command, which we
106
+
expand with the following options:
107
+
108
+
* ``-w``: set the return code to 1 if there are any warnings during the build
109
+
process.
110
+
111
+
* ``-l``: completely clean previous builds, including files generated by
112
+
the sphinx-automodapi package (which creates API pages for different
113
+
functions/classes).
114
+
115
+
* ``-n``: disable the intersphinx option.
116
+
117
+
* ``-o``: open the documentation in a browser if a build finishes successfully.
118
+
119
+
In addition, ``build_docs`` will automatically download and temporarily install
120
+
sphinx-astropy (which is a meta-package that
121
+
provides standardized configuration and documentation dependencies for astropy
122
+
packages) if it isn't already installed. Temporary installation means that the
123
+
package will be installed into an ``.eggs`` directory in the current working
124
+
directory, and it will only be available for the duration of the call to
125
+
``build_docs``.
126
+
127
+
**python setup.py build_ext**
128
+
129
+
This is also used when running ``build`` or ``install``. We add several features
130
+
compared to the default ``build_ext`` command:
131
+
132
+
* For packages with C/Cython extensions, we create a ``packagename._compiler``
133
+
submodule that contains information about the compilers used.
134
+
135
+
* Packages that need to build C extensions using the Numpy C API, we allow
136
+
those packages to define the include path as ``'numpy'`` as opposed to having
137
+
to import Numpy and call ``get_include``. The goal is to solve the issue that
138
+
if one has to import Numpy to define extensions, then Numpy has to be
139
+
installed/available before the package is installed, which means that one
140
+
needs to install Numpy in a separate installation step.
141
+
142
+
* We detect broken compilers and replace them with other compilers on-the-fly
143
+
unless the compiler is explicitly specified with the ``CC`` environment
144
+
variable.
145
+
146
+
* If Cython is not installed, then we automatically check for generated C files
147
+
(which are normally present in the stable releases) and give a nice error
148
+
if these are not found.
149
+
150
+
Version helpers
151
+
^^^^^^^^^^^^^^^^
152
+
153
+
Another piece of functionality we provide in astropy-helpers is the ability
154
+
to generate a ``packagename.version`` file that includes functions that
155
+
automatically set the version string for developer versions, to e.g.
156
+
``3.2.dev22213`` so that each developer version has a unique number (although
157
+
note that branches an equal number of commits away from the master branch will
158
+
share the same version number). To use this, import::
159
+
160
+
from astropy_helpers.git_helpers import get_git_devstr
161
+
162
+
in your ``setup.py`` file, and you will then be able to use::
163
+
164
+
VERSION += get_git_devstr()
165
+
166
+
where ``VERSION`` is a version string without any developer version suffix.
167
+
168
+
We then also provide a function that generates a ``version.py`` file inside your
169
+
package (which can then be imported as ``packagename.version``) that contains
170
+
variables such as ``major``, ``minor``, and ``bugfix``, as well as
171
+
``version_info`` (a tuple of the previous three values), a ``release`` flag that
172
+
indicates whether we are using a stable release, and several other complementary
173
+
variables. To use this, import::
174
+
175
+
from astropy_helpers.version_helpers import generate_version_py
This function declares that the package uses libraries that are
233
+
included in the astropy distribution that may also be distributed
234
+
elsewhere on the users system. It should return a list of library
235
+
names. For each library, a new build option is created,
236
+
``'--use-system-X'`` which allows the user to request to use the
237
+
system's copy of the library. The package would typically call
238
+
``astropy_helpers.setup_helpers.use_system_library`` from its
239
+
``get_extensions`` function to determine if the package should use
240
+
the system library or the included one.
241
+
242
+
* ``get_entry_points()``:
243
+
This function can returns a dict formatted as required by
244
+
the ``entry_points`` argument to ``setup()``.
245
+
246
+
With these files in place, you can then add the following to your ``setup.py``
247
+
file::
248
+
249
+
from astropy_helpers.setup_helpers import get_package_info
250
+
251
+
...
252
+
253
+
package_info = get_package_info()
254
+
255
+
...
256
+
257
+
setup(..., **package_info)
258
+
259
+
OpenMP helpers
260
+
^^^^^^^^^^^^^^
261
+
262
+
We provide a helper function ``add_openmp_flags_if_available`` that can be used
263
+
to automatically add OpenMP flags for C/Cython extensions, based on whether
264
+
OpenMP is available and produces executable code. To use this, edit the
265
+
``setup_package.py`` file where you define a C extension, import the helper
266
+
function::
267
+
268
+
from astropy_helpers.openmp_helpers import add_openmp_flags_if_available
269
+
270
+
then once you have defined the extension and before returning it, use it as::
271
+
272
+
extension = Extension(...)
273
+
274
+
add_openmp_flags_if_available(extension)
275
+
276
+
return [extension]
277
+
278
+
Using astropy-helpers
279
+
---------------------
280
+
281
+
The easiest way to get set up with astropy-helpers in a new package is to use
282
+
the `package-template <http://docs.astropy.org/projects/package-template>`_
283
+
that we provide. This template is specifically designed for use with the helpers,
284
+
so using it avoids some of the tedium of setting up the heleprs.
285
+
286
+
However, we now go through the steps of adding astropy-helpers
287
+
as a submodule to a package in case you wish to do so manually. First, add
288
+
astropy-helpers as a submodule at the root of your repository::
0 commit comments