CONTRIBUTING.rst

Building the Python Cookbook

The python cookbook uses the Sphinx documentation system.

Running make py from the cookbook root directory (the one where the README.rst exists) will install all necessary dependencies and will compile the cookbook to HTML.

You will see the compiled result inside the build/py directory.

Testing Python Recipes

All recipes in the cookbook must be tested. The cookbook uses doctest to verify the recipes.

Running make pytest from the cookbook root directory will verify that the code for all the recipes runs correctly and provides the expected output.

If the environment variable ARROW_NIGHTLY is set to 1 the cookbooks will be run against the latest development version of Arrow published by the Nightly jobs.

Example to run the cookbooks using the nightly jobs:

` $ ARROW_NIGHTLY=1 $ make pytest `

Adding Python Recipes

The recipes are written in reStructuredText format using the Sphinx documentation system.

New recipes can be added to one of the existing .rst files if they suit that section or you can create new sections by adding additional .rst files in the source directory. You just need to remember to add them to the index.rst file in the toctree for them to become visible.

The only requirement for recipes is that each code block in the recipe must be written using the .. testcode:: directive, so that it can get tested.

If the code block changes, alters or creates data, the recipe should print the data to show how it changed and have a .. testoutput:: directive to confirm that the printed data is the expected one.

For example a new recipe about how to create an Arrow array might look like:

You can create a new :class:`pyarrow.Array` providing the
data for the array through the :meth:`pyarrow.array` factory function

.. testcode::

    import pyarrow as pa
    array = pa.array(range(5))
    print(array)

.. testoutput::

    [
      0,
      1,
      2,
      3,
      4
    ]

If you refer to any pyarrow class, function or method using :class:, :meth: or :func: directives a link to their documentation in the pyarrow API reference will be automatically created.

---

All participation in the Apache Arrow project is governed by the Apache Software Foundation’s code of conduct.