.. _platforms-and-python-tags:

===========================
 Platforms and Python Tags
===========================

Brood identifies platforms and Python runtime compatibility based on
identification strings.  This section describes how to discover the
valid platforms and Python tags using ``hatcher``.

.. contents::


Platforms
=========

Platforms describe the operating system and system architecture
compatibility of an egg, runtime or app.

.. _list-platforms:

Listing current platforms recognized by a brood server
------------------------------------------------------

.. include:: list-platforms.rst

Example Valid Platforms
-----------------------

As of Brood ``v0.3.1``, the following platforms are recognized:

+----------------+-------------------+---------------------+
| Brood Platform | Operating System  | System Architecture |
+================+===================+=====================+
| ``osx-x86_64`` | Apple Mac OSX     | x86_64              |
+----------------+-------------------+---------------------+
| ``osx-x86``    | Apple Mac OSX     | x86                 |
+----------------+-------------------+---------------------+
| ``rh5-x86_64`` | RedHat Linux 5.x  | x86_64              |
+----------------+-------------------+---------------------+
| ``rh5-x86``    | RedHat Linux 5.x  | x86                 |
+----------------+-------------------+---------------------+
| ``win-x86_64`` | Microsoft Windows | x86_64              |
+----------------+-------------------+---------------------+
| ``win-x86``    | Microsoft Windows | x86                 |
+----------------+-------------------+---------------------+


.. _python-tags:

Python Tags
===========

Python tags describe the *runtime* compatibility of an egg or app.  The
Python tags are used as defined in PEP425_, following the actual
implementation in wheel_, which does not follow the spec exactly.

.. _PEP425: http://legacy.python.org/dev/peps/pep-0425/

.. _wheel: https://pypi.python.org/pypi/wheel


Python tags are used to indicate both which Python implementation a
package requires (if any), as well as the version required.  The tag is
made up of two portions which describe this relationship.  The tags
defined in PEP425_ take the following form:

* First two characters contain Python implementation description

* Final one or two characters are the ``Major`` and ``Minor`` version of
  the Python implementation.  Brood (as wheel_) use the ``Major`` and
  ``Minor`` version of the Python language that the implementation
  provides.

For example:

* ``cp27`` indicates CPython ``2.7.x`` compatibility.

* ``pp27`` indicates compatibility with Pypy providing Python language
  version ``2.7.x``.

* ``py34`` indicates that an egg has no dependency on a specific Python
  implementation, but requires Python language version ``3.4.x``.

* ``jy2`` indicates that an egg is compatible with any Jython version
  that provides Python language ``2.x``.


.. _list-python-tags:

Python Tags and Eggs
--------------------

When requesting an egg list or index, the Python tag of the target
runtime must be provided.  This is to ensure that the index returned
contains only packages that will work on the target runtime.  To list
the possible Python tags that may be used to request the egg list for a
Python implementation, use the following command::

    $ hatcher python-tags list
    Python Tag
    ------------
    cp27
    cp30
    cp31
    cp32
    cp33
    cp34
    ip27
    jy27
    pp27


Each egg in Brood specifies its own Python runtime compatibility.  For
example, ``numpy`` requires a CPython interpreter as it depends on the
CPython/C API.  It may specify a Python tag like ``cp27`` or ``cp32``.
On the other hand, ``nose`` is a pure-python egg which is compatible
with multiple runtimes.  It may specify Python tags like ``py2`` and
``py3``.  When listing eggs with hatcher, the eggs specific runtime tag
is listed along with it, so that the correct egg may be manipulated with
hatcher::

    $ hatcher eggs list enthought free rh5-64 cp27
    Egg Name          Python Tag
    ----------------  ------------
    nose-1.3.0-1.egg  py2
    ...

The Python tag listed alongside the egg is used to download the egg::

    $ hatcher eggs download enthought free rh5-64 py2 nose 1.3.0-1
    ...