- python3 -m pip install --upgrade mypy coverage sphinx

- python3 setup.py build_sphinx

extensions = ['sphinx.ext.autodoc',

'sphinx.ext.doctest',

'sphinx.ext.intersphinx',

'sphinx.ext.coverage',

'sphinx.ext.viewcode']

templates_path = ['_templates']

source_suffix = '.rst'

master_doc = 'index'

project = 'importlib_resources'

copyright = '2017, Brett Cannon, Barry Warsaw'

author = 'Brett Cannon, Barry Warsaw'

version = '0.1'

release = '0.1'

language = None

exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

pygments_style = 'sphinx'

todo_include_todos = False

html_theme = 'alabaster'

html_static_path = ['_static']

html_sidebars = {

'**': [

'relations.html', # needs 'show_related': True theme option to display

'searchbox.html',

]

}

htmlhelp_basename = 'importlib_resourcesdoc'

latex_elements = {

# The paper size ('letterpaper' or 'a4paper').

#

# 'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').

#

# 'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.

#

# 'preamble': '',

# Latex figure (float) alignment

#

# 'figure_align': 'htbp',

}

latex_documents = [

(master_doc, 'importlib_resources.tex', 'importlib\\_resources Documentation',

'Brett Cannon, Barry Warsaw', 'manual'),

]

man_pages = [

(master_doc, 'importlib_resources', 'importlib_resources Documentation',

[author], 1)

]

texinfo_documents = [

(master_doc, 'importlib_resources', 'importlib_resources Documentation',

author, 'importlib_resources', 'One line description of project.',

'Miscellaneous'),

]

intersphinx_mapping = {

'python': ('https://docs.python.org', None),

}

Welcome to importlib_resources

``importlib_resources`` is a library which provides for access to *resources*

in Python packages. It provides functionality similar to ``pkg_resources``

`Basic Resource Access`_ API, but without all of the overhead and performance

problems of ``pkg_resources``.

In our terminology, a *resource* is a file that is located within an

importable `Python package`_. Resources can live on the file system, in a zip

file, or in any place that has a loader_ supporting the appropriate API for

reading resources. Directories are not resources.

``importlib_resources`` is a standalone version of the API available for users

of Python 2.7, or Python 3.4 through 3.6. It is available in Python 3.7's

standard library as ``importlib.resources``. Its API is currently

`provisional`_.

This documentation includes a general :ref:`usage <using>` guide and a

:ref:`migration` guide for projects which want to adopt

``importlib_resources`` instead of ``pkg_resources``.

.. toctree::

:maxdepth: 2

:caption: Contents:

using.rst

migration.rst

Indices and tables

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

.. _`Basic Resource Access`: http://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access

.. _`provisional`: https://www.python.org/dev/peps/pep-0411/

.. _`Python package`: https://docs.python.org/3/reference/import.html#packages

.. _loader: https://docs.python.org/3/reference/import.html#finders-and-loaders

.. _migration:

Migration guide

The following guide will help you migrate common ``pkg_resources`` APIs to

``importlib_resources``. Only a small number of the most common APIs are

supported by ``importlib_resources``, so projects that use other features

(e.g. entry points) will have to find other solutions.

``importlib_resources`` primarily supports the following `basic resource

access`_ APIs:

* ``pkg_resources.resource_filename()``

* ``pkg_resources.resource_stream()``

* ``pkg_resources.resource_string()``

Keep in mind that ``pkg_resources`` defines *resources* to include

directories. ``importlib_resources`` does not treat directories as resources;

since only file are allowed as resources, file names in the

``importlib_resources`` API may *not* include path separators (e.g. slashes).

resource_filename()

``resource_filename()`` is one of the more interesting APIs because it

guarantees that the return value names a file on the file system. This means

that if the resource is in a zip file, ``pkg_resources()`` will extract the

file and return the name of the temporary file it created. The problem is

that ``pkg_resources()`` also *implicitly* cleans up this temporary file,

without control or its lifetime by the programmer.

``importlib_resources`` takes a different approach. Its equivalent API is the

``path()`` function, which returns a context manager providing a

:py:class:`pathlib.Path` object. This means users have both the flexibility

and responsibility to manage the lifetime of the temporary file. Note though

that if the resource is *already* on the file system, ``importlib_resources``

still returns a context manager, but nothing needs to get cleaned up.

Here's an example from ``pkg_resources()``::

The best way to convert this is with the following idiom::

That's all fine is you only need the file temporarily, but what if you need it

to stick around for a while? One way of doing this is to use an

:py:class:`contextlib.ExitStack` instance and manage the resource explicitly::

Now ``path`` will continue to exist until you explicitly call

``file_manager.close()``. What if you want the file to exist until the

process exits, or you can't pass ``file_manager`` around in your code? Use an

:py:mod:`atexit` handler::

Assuming your Python interpreter exits gracefully, the temporary file will be

cleaned up when Python exits.

resource_stream()

``pkg_resources.resource_stream()`` returns a readable file-like object opened

in binary mode. When you read from the returned file-like object, you get

bytes. E.g.::

The equivalent code in ``importlib_resources`` is pretty straightforward::

resource_string()

In Python 2, ``pkg_resources.resource_string()`` returns the contents of a

resource as a ``str``. In Python 3, this function is a misnomer; it actually

returns the contents of the named resource as ``bytes``. That's why the

following example is often written for clarity as::

This can be easily rewritten like so::

The ``encoding=None`` argument is needed because by default ``read()`` returns

a ``unicode`` in Python 2 or a ``str`` in Python 3, read and decoded with the

``utf-8`` encoding.

.. _`basic resource access`: http://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access