datadir-ng plugin for pytest |pypi-badge|
=========================================
The ``datadir-ng`` plugin for pytest_ provides the ``datadir``
and ``datadir_copy`` fixtures which allow test functions to easily access resources
in data directories. It was inspired by the `pytest-datadir plugin`_ and is intended
to be a more flexible version of that plugin (hence the "ng" part in its name -- as
in "next generation").
This plugin provides two fixtures:
- The datadir_ fixture allows test functions and methods to access resources in
so-called "data directories".
- The `datadir_copy`_ fixture is similar to the datadir_ fixture, but it copies the
requested resources to a temporary directory first so that test functions or
methods can modify their resources on-disk without affecting other test functions
and methods.
Installation
------------
Just do::
pip install pytest-datadir-ng
.. _datadir:
The datadir fixture
-------------------
The "datadir" fixture allows test functions and methods to access resources in
so-called "data directories".
The fixture behaves like a dictionary. Currently, only retrieving items using the
``d[key]`` syntax is supported. Things like iterators, ``len(d)`` etc. are not.
How the fixture looks for resources is best described by an example.
Let us assume the following directory structure for your tests::
tests/
+-- test_one.py
+-- test_two.py
+-- data/
| +-- global.dat
+-- test_one/
| +-- test_func/
| +-- data.txt
+-- test_two/
+-- TestClass/
+-- test_method/
+-- strings.prop
The file ``test_one.py`` contains the following function:
.. code:: python
def test_func(datadir):
data_path = datadir["data.txt"]
# ...
The file ``test_two.py`` contains the following class:
.. code:: python
class TestClass(object):
def test_method(self, datadir):
strings_path = datadir["strings.prop"]
# ...
When the ``test_func()`` function asks for the ``data.txt`` resource, the
following directories are searched for a file or directory named ``data.txt``,
in this order:
- ``tests/test_one/test_func/``
- ``tests/test_one/``
- ``tests/data/test_one/test_func/``
- ``tests/data/test_one/``
- ``tests/data/``
The path to the first existing file (or directory) is returned as a
py.path.local_ object. In this case, the returned path would be
``tests/test_one/test_func/data.txt``.
When the ``test_method()`` method asks for the ``strings.prop`` resource,
the following directories are searched for a file or directory with the name
``strings.prop``, in this order:
- ``tests/test_two/TestClass/test_method/``
- ``tests/test_two/TestClass/``
- ``tests/test_two/``
- ``tests/data/test_two/TestClass/test_method/``
- ``tests/data/test_two/TestClass/``
- ``tests/data/test_two/``
- ``tests/data/``
Here, this would return the path
``tests/test_two/TestClass/test_method/strings.prop``.
As you can see, the searched directory hierarchy is slighly different if a
*method* instead of a *function* asks for a resource. This allows you to
load different resources based on the name of the test class, if you wish.
Finally, if a test function or test method would ask for a resource named
``global.dat``, then the resulting path would be ``tests/data/global.dat``
since no other directory in the searched directory hierarchy contains
a file named ``global.dat``. In other words, the ``tests/data/`` directory
is the place for global (or fallback) resources.
If a resource cannot be found in *any* of the searched directories, a
`KeyError` is raised.
.. _datadir_copy:
The datadir_copy fixture
------------------------
The "datadir_copy" fixture is similar to the datadir_ fixture, but copies the requested resources to a
temporary directory first so that test functions or methods can modify their resources on-disk without affecting
other test functions and methods.
Each test function or method gets its own temporary directory and thus its own fresh copies of the resources it
requests.
**Caveat:** Each time a resource is requested using the dictionary notation, a fresh copy of the resource is made.
This also applies if a test function or method requests the same resource multiple times. Thus, if you modify a
resource and need to access the *modified* version of the resource later, save its path in a variable and use that
variable to access the resource later instead of using the dictionary notation multiple times:
.. code:: python
def test_foo(datadir_copy):
# This creates the initial fresh copy of data.txt and saves
# its path in the variable "resource1".
resource1 = datadir_copy["data.txt"]
# ...modify resource1 on-disk...
# You now want to access the modified version of data.txt.
# WRONG way: This will overwrite your modified version of the
# resource with a fresh copy!
fh = datadir_copy["data.txt"].open("rb")
# CORRECT way: This will let you access the modified version
# of the resource.
fh = resource1.open("rb")
Version history
---------------
Version 1.1.1
+++++++++++++
- Add a `LICENSE` file (fixes #3).
Version 1.1.0
+++++++++++++
- Allow per-test directories under ``data/`` (thanks, Alexander Lukanin).
Version 1.0.1
+++++++++++++
- Added this `Version history`_ section. :-)
- Fixed bad usage of py.path.local_ objects in code examples.
Version 1.0.0
+++++++++++++
- Initial release
..
NB: Without a trailing question mark in the following image URL, the
generated HTML will contain an <object> element instead of an <img>
element, which apparently cannot be made into a link (i. e. a
"clickable" image).
.. |pypi-badge| image:: https://img.shields.io/pypi/v/pytest-datadir-ng.svg?
:align: middle
:target: https://pypi.python.org/pypi/pytest-datadir-ng
.. _pytest: http://pytest.org/
.. _pytest-datadir plugin: https://github.com/gabrielcnr/pytest-datadir
.. _py.path.local: http://pylib.readthedocs.org/en/latest/path.html
Raw data
{
"_id": null,
"home_page": "https://github.com/Tblue/pytest-datadir-ng",
"name": "pytest-datadir-ng",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "py.test resources files data directory directories",
"author": "Tilman Blumenbach",
"author_email": "tilman+pypi@ax86.net",
"download_url": "https://files.pythonhosted.org/packages/1a/d6/812562c99bfb8870e897f6d9a0af4d116118144b205257f9778c51481f99/pytest-datadir-ng-1.1.1.tar.gz",
"platform": "",
"description": "datadir-ng plugin for pytest |pypi-badge|\n=========================================\n\nThe ``datadir-ng`` plugin for pytest_ provides the ``datadir``\nand ``datadir_copy`` fixtures which allow test functions to easily access resources\nin data directories. It was inspired by the `pytest-datadir plugin`_ and is intended\nto be a more flexible version of that plugin (hence the \"ng\" part in its name -- as\nin \"next generation\").\n\nThis plugin provides two fixtures:\n\n- The datadir_ fixture allows test functions and methods to access resources in\n so-called \"data directories\".\n- The `datadir_copy`_ fixture is similar to the datadir_ fixture, but it copies the\n requested resources to a temporary directory first so that test functions or\n methods can modify their resources on-disk without affecting other test functions\n and methods.\n\nInstallation\n------------\n\nJust do::\n\n pip install pytest-datadir-ng\n\n.. _datadir:\n\nThe datadir fixture\n-------------------\n\nThe \"datadir\" fixture allows test functions and methods to access resources in\nso-called \"data directories\".\n\nThe fixture behaves like a dictionary. Currently, only retrieving items using the\n``d[key]`` syntax is supported. Things like iterators, ``len(d)`` etc. are not.\n\nHow the fixture looks for resources is best described by an example.\nLet us assume the following directory structure for your tests::\n\n tests/\n +-- test_one.py\n +-- test_two.py\n +-- data/\n | +-- global.dat\n +-- test_one/\n | +-- test_func/\n | +-- data.txt\n +-- test_two/\n +-- TestClass/\n +-- test_method/\n +-- strings.prop\n\nThe file ``test_one.py`` contains the following function:\n\n.. code:: python\n\n def test_func(datadir):\n data_path = datadir[\"data.txt\"]\n\n # ...\n\nThe file ``test_two.py`` contains the following class:\n\n.. code:: python\n\n class TestClass(object):\n def test_method(self, datadir):\n strings_path = datadir[\"strings.prop\"]\n\n # ...\n\nWhen the ``test_func()`` function asks for the ``data.txt`` resource, the\nfollowing directories are searched for a file or directory named ``data.txt``,\nin this order:\n\n- ``tests/test_one/test_func/``\n- ``tests/test_one/``\n- ``tests/data/test_one/test_func/``\n- ``tests/data/test_one/``\n- ``tests/data/``\n\nThe path to the first existing file (or directory) is returned as a\npy.path.local_ object. In this case, the returned path would be\n``tests/test_one/test_func/data.txt``.\n\nWhen the ``test_method()`` method asks for the ``strings.prop`` resource,\nthe following directories are searched for a file or directory with the name\n``strings.prop``, in this order:\n\n- ``tests/test_two/TestClass/test_method/``\n- ``tests/test_two/TestClass/``\n- ``tests/test_two/``\n- ``tests/data/test_two/TestClass/test_method/``\n- ``tests/data/test_two/TestClass/``\n- ``tests/data/test_two/``\n- ``tests/data/``\n\nHere, this would return the path\n``tests/test_two/TestClass/test_method/strings.prop``.\n\nAs you can see, the searched directory hierarchy is slighly different if a\n*method* instead of a *function* asks for a resource. This allows you to\nload different resources based on the name of the test class, if you wish.\n\nFinally, if a test function or test method would ask for a resource named\n``global.dat``, then the resulting path would be ``tests/data/global.dat``\nsince no other directory in the searched directory hierarchy contains\na file named ``global.dat``. In other words, the ``tests/data/`` directory\nis the place for global (or fallback) resources.\n\nIf a resource cannot be found in *any* of the searched directories, a\n`KeyError` is raised.\n\n.. _datadir_copy:\n\nThe datadir_copy fixture\n------------------------\n\nThe \"datadir_copy\" fixture is similar to the datadir_ fixture, but copies the requested resources to a\ntemporary directory first so that test functions or methods can modify their resources on-disk without affecting\nother test functions and methods.\n\nEach test function or method gets its own temporary directory and thus its own fresh copies of the resources it\nrequests.\n\n**Caveat:** Each time a resource is requested using the dictionary notation, a fresh copy of the resource is made.\nThis also applies if a test function or method requests the same resource multiple times. Thus, if you modify a\nresource and need to access the *modified* version of the resource later, save its path in a variable and use that\nvariable to access the resource later instead of using the dictionary notation multiple times:\n\n.. code:: python\n\n def test_foo(datadir_copy):\n # This creates the initial fresh copy of data.txt and saves\n # its path in the variable \"resource1\".\n resource1 = datadir_copy[\"data.txt\"]\n\n # ...modify resource1 on-disk...\n\n # You now want to access the modified version of data.txt.\n\n # WRONG way: This will overwrite your modified version of the\n # resource with a fresh copy!\n fh = datadir_copy[\"data.txt\"].open(\"rb\")\n\n # CORRECT way: This will let you access the modified version\n # of the resource.\n fh = resource1.open(\"rb\")\n\nVersion history\n---------------\n\nVersion 1.1.1\n+++++++++++++\n\n- Add a `LICENSE` file (fixes #3).\n\nVersion 1.1.0\n+++++++++++++\n\n- Allow per-test directories under ``data/`` (thanks, Alexander Lukanin).\n\nVersion 1.0.1\n+++++++++++++\n\n- Added this `Version history`_ section. :-)\n- Fixed bad usage of py.path.local_ objects in code examples.\n\nVersion 1.0.0\n+++++++++++++\n\n- Initial release\n\n\n..\n NB: Without a trailing question mark in the following image URL, the\n generated HTML will contain an <object> element instead of an <img>\n element, which apparently cannot be made into a link (i. e. a\n \"clickable\" image).\n.. |pypi-badge| image:: https://img.shields.io/pypi/v/pytest-datadir-ng.svg?\n :align: middle\n :target: https://pypi.python.org/pypi/pytest-datadir-ng\n\n.. _pytest: http://pytest.org/\n.. _pytest-datadir plugin: https://github.com/gabrielcnr/pytest-datadir\n.. _py.path.local: http://pylib.readthedocs.org/en/latest/path.html\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Fixtures for pytest allowing test functions/methods to easily retrieve test resources from the local filesystem.",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/Tblue/pytest-datadir-ng"
},
"split_keywords": [
"py.test",
"resources",
"files",
"data",
"directory",
"directories"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c598d4b1344e2f307d7707e5f113409442c2879657fb76880621697074176dce",
"md5": "b9c84b75da30aaba288cb1a93fe77d96",
"sha256": "7fec7a4996a12529a935512c128624fa7289495b520fd31b4645c3a71daa394e"
},
"downloads": -1,
"filename": "pytest_datadir_ng-1.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9c84b75da30aaba288cb1a93fe77d96",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 7682,
"upload_time": "2019-12-25T02:23:41",
"upload_time_iso_8601": "2019-12-25T02:23:41.543844Z",
"url": "https://files.pythonhosted.org/packages/c5/98/d4b1344e2f307d7707e5f113409442c2879657fb76880621697074176dce/pytest_datadir_ng-1.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1ad6812562c99bfb8870e897f6d9a0af4d116118144b205257f9778c51481f99",
"md5": "fe2af071333902c9c81b072334611049",
"sha256": "0d9e0212eaa4d0440a4b7c3d2df4b4b7eeebde1854ab383c5aff590764ad8a52"
},
"downloads": -1,
"filename": "pytest-datadir-ng-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "fe2af071333902c9c81b072334611049",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7835,
"upload_time": "2019-12-25T02:23:43",
"upload_time_iso_8601": "2019-12-25T02:23:43.374780Z",
"url": "https://files.pythonhosted.org/packages/1a/d6/812562c99bfb8870e897f6d9a0af4d116118144b205257f9778c51481f99/pytest-datadir-ng-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-12-25 02:23:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Tblue",
"github_project": "pytest-datadir-ng",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "pytest-datadir-ng"
}
JSON
