Astropy Documentation Release 0.2.5 The Astropy Developers October 28, 2013 CONTENTS i ii Astropy Documentation, Release 0.2.5 Astropy is a community-driven package intended to contain much of the core functionality and some common tools needed for performing astronomy and astrophysics with Python. CONTENTS 1 Astropy Documentation, Release 0.2.5 2 CONTENTS Part I User Documentation 3 Astropy Documentation, Release 0.2.5 Astropy at a glance 5 Astropy Documentation, Release 0.2.5 6 CHAPTER ONE OVERVIEW Here we describe a broad overview of the Astropy project and its parts. 1.1 Astropy Project Concept The “Astropy Project” is distinct from the astropy package. The Astropy Project is a process intended to facilitate communication and interoperability of python packages/codes in astronomy and astrophysics. The project thus en- compasses the astropy core package (which provides a common framework), all “affiliated packages” (described below in Affiliated Packages), and a general community aimed at bringing resources together and not duplicating efforts. 1.2 astropy Core Package The astropy package (alternatively known as the “core” package) contains various classes, utilities, and a packaging framework intended to provide commonly-used astronomy tools. It is divided into a variety of sub-packages, which are documented in the remainder of this documentation (see User Documentation for documentation of these components). The core also provides this documentation, and a variety of utilities that simplify starting other python astron- omy/astrophysics packages. As described in the following section, these simplify the process of creating affiliated packages. 1.3 Affiliated Packages The Astropy project includes the concept of “affiliated packages.” An affiliated package is an astronomy-related python package that is not part of the astropy core source code, but has requested to be included in the Astropy project. Such a package may be a candidate for eventual inclusion in the main astropy package (although this is not required). There is a registry of affiliated packages at http://affiliated.astropy.org, and in the near future, the astropy core will include a tool to install affiliated packages by name. See the config module documentation for details about the affiliated package registry and install tool. Note that affiliated packages do not use the astropy namespace, which is reserved for the core. Instead, they either use their package name directly, or awastropy.packagename (“affiliated with astropy”). If you are interested in starting an affiliated package, or have a package you are interested in making more compatible with astropy, the astropy core package includes a variety of features that simplify and homogenize package man- agement. Astropy provides a package template that provides a common way to organize packages, to make your life 7 Astropy Documentation, Release 0.2.5 simpler. You can use this template either with a new package you are starting or an existing package to make it more compatible with Astropy and the affiliated package installer. See the usage instructions in the template for further details. 1.4 Community Aside from the actual code, Astropy is also a community of astronomy-associated users and developers that agree that sharing utilities is healthy for the community and the science it produces. This community is of course central to accomplishing anything with the code itself. 8 Chapter 1. Overview CHAPTER TWO INSTALLATION 2.1 Requirements Astropy has the following strict requirements: • Python 2.6, 2.7, 3.1 or 3.2 • Numpy 1.4 or later Astropy also depends on other packages for optional features: • h5py: To read/write Table objects from/to HDF5 files • scipy: To power a variety of features (currently mainly cosmology-related functionality) • xmllint: To validate VOTABLE XML files. However, note that these only need to be installed if those particular features are needed. Astropy will import even if these dependencies are not installed. 2.2 Installing Astropy 2.2.1 Using pip To install Astropy with pip, simply run: pip install --no-deps astropy Note: You will need a C compiler (e.g. gcc or clang) to be installed (see Building from source below) for the installation to succeed. Note: The --no-deps flag is optional, but highly recommended if you already have Numpy installed, since otherwise pip will sometimes try to “help” you by upgrading your Numpy installation, which may not always be desired. Note: If you get a PermissionError this means that you do not have the required administrative access to install new packages to your Python installation. In this case you may consider using the --user option to install the package into your home directory. You can read more about how to do this in the pip documentation. Alternatively, if you intend to do development on other software that uses Astropy, such as an affiliated package, consider installing Astropy into a virtualenv. 9 Astropy Documentation, Release 0.2.5 Do not install Astropy or other third-party packages using sudo unless you are fully aware of the risks. 2.2.2 Binary installers Binary installers are available on Windows for Python 2.6, 2.7, 3.1, and 3.2 at PyPI. 2.2.3 Testing an installed Astropy The easiest way to test your installed version of astropy is running correctly is to use the astropy.test() function: import astropy astropy.test() The tests should run and print out any failures, which you can report at the Astropy issue tracker. Note: This way of running the tests may not work if you do it in the astropy source distribution. See Testing a source code build of Astropy for how to run the tests from the source code directory, or Running Tests for more details. 2.3 Building from source 2.3.1 Prerequisites You will need a compiler suite and the development headers for Python and Numpy in order to build Astropy. On Linux, using the package manager for your distribution will usually be the easiest route, while on MacOS X you will need the XCode command line tools. The instructions for building Numpy from source are also a good resource for setting up your environment to build Python packages. You will also need Cython installed to build from source, unless you are installing a numbered release. (The releases packages have the necessary C files packaged with them, and hence do not require Cython.) Note: If you are using MacOS X, you will need to the XCode command line tools. One way to get them is to install XCode. If you are using OS X 10.7 (Lion) or later, you must also explicitly install the command line tools. You can do this by opening the XCode application, going to Preferences, then Downloads, and then under Components, click on the Install button to the right of Command Line Tools. Alternatively, on 10.7 (Lion) or later, you do not need to in- stall XCode, you can download just the command line tools from https://developer.apple.com/downloads/index.action (requires an Apple developer account). 2.3.2 Obtaining the source packages Source packages The latest stable source package for Astropy can be downloaded here. 10 Chapter 2. Installation Astropy Documentation, Release 0.2.5 Development repository The latest development version of Astropy can be cloned from github using this command: git clone git://github.com/astropy/astropy.git Note: If you wish to participate in the development of Astropy, see Developer Documentation. This document covers only the basics necessary to install Astropy. 2.3.3 Building and Installing Astropy uses the Python distutils framework for building and installing and requires the distribute extension–the later is automatically downloaded when running python setup.py if it is not already provided by your system. To build Astropy (from the root of the source tree): python setup.py build To install Astropy (from the root of the source tree): python setup.py install 2.3.4 Troubleshooting If you get an error mentioning that you do not have the correct permissions to install Astropy into the default site-packages directory, you can try installing with: python setup.py install --user which will install into a default directory in your home directory. External C libraries The Astropy source ships with the C source code of a number of libraries. By default, these internal copies are used to build Astropy. However, if you wish to use the system-wide installation of one of those libraries, you can pass one or more of the --use-system-X flags to the setup.py build command. For example, to build Astropy using the system libexpat, use: python setup.py build --use-system-expat To build using all of the system libraries, use: python setup.py build --use-system-libraries To see which system libraries Astropy knows how to build against, use: python setup.py build --help As with all distutils commandline options, they may also be provided in a setup.cfg in the same directory as setup.py. For example, to use the system libexpat, add the following to the setup.cfg file: [build] use_system_expat=1 2.3. Building from source 11 Astropy Documentation, Release 0.2.5 The required version of setuptools is not available If upon running the setup.py script you get a message like The required version of setuptools (>=0.9.8) is not available, and can’t be installed while this script is running. Please install a more recent version first, using ‘easy_install -U setuptools’. (Currently using setuptools 0.6c11 (/path/to/setuptools-0.6c11-py2.7.egg)) this is because you have a very outdated version of the setuptools package which is used to install Python packages.