--------------------------------------------------------------
pox: utilities for filesystem exploration and automated builds
--------------------------------------------------------------
About Pox
=========
``pox`` provides a collection of utilities for navigating and manipulating
filesystems. This module is designed to facilitate some of the low level
operating system interactions that are useful when exploring a filesystem
on a remote host, where queries such as *"what is the root of the filesystem?"*,
*"what is the user's name?"*, and *"what login shell is preferred?"* become
essential in allowing a remote user to function as if they were logged in
locally. While ``pox`` is in the same vein of both the ``os`` and ``shutil``
builtin modules, the majority of its functionality is unique and compliments
these two modules.
``pox`` provides Python equivalents of several unix shell commands such as
``which`` and ``find``. These commands allow automated discovery of what has
been installed on an operating system, and where the essential tools are
located. This capability is useful not only for exploring remote hosts,
but also locally as a helper utility for automated build and installation.
Several high-level operations on files and filesystems are also provided.
Examples of which are: finding the location of an installed Python package,
determining if and where the source code resides on the filesystem, and
determining what version the installed package is.
``pox`` also provides utilities to enable the abstraction of commands sent
to a remote filesystem. In conjunction with a registry of environment
variables and installed utilites, ``pox`` enables the user to interact with
a remote filesystem as if they were logged in locally.
``pox`` is part of ``pathos``, a Python framework for heterogeneous computing.
``pox`` is in active development, so any user feedback, bug reports, comments,
or suggestions are highly appreciated. A list of issues is located at https://github.com/uqfoundation/pox/issues, with a legacy list maintained at https://uqfoundation.github.io/project/pathos/query.
Major Features
==============
``pox`` provides utilities for discovering the user's environment:
- return the user's name, current shell, and path to user's home directory
- strip duplicate entries from the user's ``$PATH``
- lookup and expand environment variables from ``${VAR}`` to ``value``
``pox`` also provides utilities for filesystem exploration and manipulation:
- discover the path to a file, exectuable, directory, or symbolic link
- discover the path to an installed package
- parse operating system commands for remote shell invocation
- convert text files to platform-specific formatting
Current Release
===============
The latest released version of ``pox`` is available from:
https://pypi.org/project/pox
``pox`` is distributed under a 3-clause BSD license.
Development Version
===================
You can get the latest development version with all the shiny new features at:
https://github.com/uqfoundation
If you have a new contribution, please submit a pull request.
Installation
============
``pox`` can be installed with ``pip``::
$ pip install pox
Requirements
============
``pox`` requires:
- ``python`` (or ``pypy``), **>=3.8**
- ``setuptools``, **>=42**
Basic Usage
===========
``pox`` includes some basic utilities to connect to and automate exploration
on local and remote filesystems. There are some basic functions to discover
important locations::
>>> import pox
>>> pox.homedir()
'/Users/mmckerns'
>>> pox.rootdir()
'/'
or, you can interact with local and global environment variables::
>>> local = {'DEV':'${HOME}/dev', 'FOO_VERSION':'0.1', 'BAR_VERSION':'1.0'}
>>> pox.getvars('${DEV}/lib/foo-${FOO_VERSION}', local)
{'DEV': '${HOME}/dev', 'FOO_VERSION': '0.1'}
>>> pox.expandvars('${DEV}/lib/foo-${FOO_VERSION}', local)
'${HOME}/dev/lib/foo-0.1'
>>> pox.expandvars('${HOME}/dev/lib/foo-0.1')
'/Users/mmckerns/dev/lib/foo-0.1'
>>> pox.env('HOME')
{'HOME': '/Users/mmckerns'}
and perform some basic search functions::
>>> pox.find('python3.9', recurse=5, root='/opt')
['/opt/local/bin/python3.9']
>>> pox.which('python3.9')
'/opt/local/bin/python3.9'
``pox`` also has a specialized `which` command just for Python::
>>> pox.which_python()
'/opt/local/bin/python3.9'
>>> pox.which_python(lazy=True, version=True)
'`which python3.9`'
Any of the ``pox`` functions can be launched from the command line,
which facilitates executing commands across parallel and distributed pipes
(such as `pathos.connection.Pipe` and `pathos.secure.connection.Pipe`)::
>>> import pathos
>>> p = pathos.connection.Pipe()
>>> p(command="python -m pox 'which_python()'")
>>> p.launch()
>>> print(p.response())
'/usr/bin/python'
>>> p.kill()
The functions in ``pox`` that help make interactions with filesystems and
environment varialbles programmatic and abstract become especially relevant
when trying to execute complex commands remotely.
More Information
================
Probably the best way to get started is to look at the documentation at
http://pox.rtfd.io. Also see ``pox.tests`` for a set of scripts that demonstrate
how ``pox`` can be used to interact with the operating system. You can run the
test suite with ``python -m pox.tests``. All ``pox`` utilities
can be launched directly from an operating system terminal, using the ``pox``
script (or with ``python -m pox``). The source code is also generally well
documented, so further questions may be resolved by inspecting the code
itself. Please feel free to submit a ticket on github, or ask a
question on stackoverflow (**@Mike McKerns**).
If you would like to share how you use ``pox`` in your work, please send an
email (to **mmckerns at uqfoundation dot org**).
Citation
========
If you use ``pox`` to do research that leads to publication, we ask that you
acknowledge use of ``pox`` by citing the following in your publication::
M.M. McKerns, L. Strand, T. Sullivan, A. Fang, M.A.G. Aivazis,
"Building a framework for predictive science", Proceedings of
the 10th Python in Science Conference, 2011;
http://arxiv.org/pdf/1202.1056
Michael McKerns and Michael Aivazis,
"pathos: a framework for heterogeneous computing", 2010- ;
https://uqfoundation.github.io/project/pathos
Please see https://uqfoundation.github.io/project/pathos or
http://arxiv.org/pdf/1202.1056 for further information.
Raw data
{
"_id": null,
"home_page": "https://github.com/uqfoundation/pox",
"name": "pox",
"maintainer": "Mike McKerns",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "mmckerns@uqfoundation.org",
"keywords": null,
"author": "Mike McKerns",
"author_email": "mmckerns@uqfoundation.org",
"download_url": "https://files.pythonhosted.org/packages/2e/0d/f2eb94b4d1358a60f3539a6abcbbd757fbcb78538fe8d4cfa49850356ccf/pox-0.3.5.tar.gz",
"platform": "Linux",
"description": "--------------------------------------------------------------\npox: utilities for filesystem exploration and automated builds\n--------------------------------------------------------------\n\nAbout Pox\n=========\n\n``pox`` provides a collection of utilities for navigating and manipulating\nfilesystems. This module is designed to facilitate some of the low level\noperating system interactions that are useful when exploring a filesystem\non a remote host, where queries such as *\"what is the root of the filesystem?\"*,\n*\"what is the user's name?\"*, and *\"what login shell is preferred?\"* become\nessential in allowing a remote user to function as if they were logged in\nlocally. While ``pox`` is in the same vein of both the ``os`` and ``shutil``\nbuiltin modules, the majority of its functionality is unique and compliments\nthese two modules.\n\n``pox`` provides Python equivalents of several unix shell commands such as\n``which`` and ``find``. These commands allow automated discovery of what has\nbeen installed on an operating system, and where the essential tools are\nlocated. This capability is useful not only for exploring remote hosts,\nbut also locally as a helper utility for automated build and installation.\n\nSeveral high-level operations on files and filesystems are also provided.\nExamples of which are: finding the location of an installed Python package,\ndetermining if and where the source code resides on the filesystem, and\ndetermining what version the installed package is.\n\n``pox`` also provides utilities to enable the abstraction of commands sent\nto a remote filesystem. In conjunction with a registry of environment\nvariables and installed utilites, ``pox`` enables the user to interact with\na remote filesystem as if they were logged in locally. \n\n``pox`` is part of ``pathos``, a Python framework for heterogeneous computing.\n``pox`` is in active development, so any user feedback, bug reports, comments,\nor suggestions are highly appreciated. A list of issues is located at https://github.com/uqfoundation/pox/issues, with a legacy list maintained at https://uqfoundation.github.io/project/pathos/query.\n\n\nMajor Features\n==============\n\n``pox`` provides utilities for discovering the user's environment:\n\n - return the user's name, current shell, and path to user's home directory\n - strip duplicate entries from the user's ``$PATH``\n - lookup and expand environment variables from ``${VAR}`` to ``value``\n\n``pox`` also provides utilities for filesystem exploration and manipulation:\n\n - discover the path to a file, exectuable, directory, or symbolic link \n - discover the path to an installed package\n - parse operating system commands for remote shell invocation\n - convert text files to platform-specific formatting\n\n\nCurrent Release\n===============\n\nThe latest released version of ``pox`` is available from:\n\n https://pypi.org/project/pox\n\n``pox`` is distributed under a 3-clause BSD license.\n\n\nDevelopment Version\n===================\n\nYou can get the latest development version with all the shiny new features at:\n\n https://github.com/uqfoundation\n\nIf you have a new contribution, please submit a pull request.\n\n\nInstallation\n============\n\n``pox`` can be installed with ``pip``::\n\n $ pip install pox\n\n\nRequirements\n============\n\n``pox`` requires:\n\n - ``python`` (or ``pypy``), **>=3.8**\n - ``setuptools``, **>=42**\n\n\nBasic Usage\n===========\n\n``pox`` includes some basic utilities to connect to and automate exploration\non local and remote filesystems. There are some basic functions to discover\nimportant locations::\n\n >>> import pox\n >>> pox.homedir()\n '/Users/mmckerns'\n >>> pox.rootdir()\n '/'\n\nor, you can interact with local and global environment variables::\n\n >>> local = {'DEV':'${HOME}/dev', 'FOO_VERSION':'0.1', 'BAR_VERSION':'1.0'}\n >>> pox.getvars('${DEV}/lib/foo-${FOO_VERSION}', local)\n {'DEV': '${HOME}/dev', 'FOO_VERSION': '0.1'}\n >>> pox.expandvars('${DEV}/lib/foo-${FOO_VERSION}', local)\n '${HOME}/dev/lib/foo-0.1'\n >>> pox.expandvars('${HOME}/dev/lib/foo-0.1')\n '/Users/mmckerns/dev/lib/foo-0.1'\n >>> pox.env('HOME')\n {'HOME': '/Users/mmckerns'}\n\nand perform some basic search functions::\n\n >>> pox.find('python3.9', recurse=5, root='/opt')\n ['/opt/local/bin/python3.9']\n >>> pox.which('python3.9')\n '/opt/local/bin/python3.9'\n\n``pox`` also has a specialized `which` command just for Python::\n\n >>> pox.which_python()\n '/opt/local/bin/python3.9'\n >>> pox.which_python(lazy=True, version=True)\n '`which python3.9`'\n\nAny of the ``pox`` functions can be launched from the command line,\nwhich facilitates executing commands across parallel and distributed pipes\n(such as `pathos.connection.Pipe` and `pathos.secure.connection.Pipe`)::\n\n >>> import pathos\n >>> p = pathos.connection.Pipe()\n >>> p(command=\"python -m pox 'which_python()'\")\n >>> p.launch()\n >>> print(p.response())\n '/usr/bin/python'\n >>> p.kill()\n\nThe functions in ``pox`` that help make interactions with filesystems and\nenvironment varialbles programmatic and abstract become especially relevant\nwhen trying to execute complex commands remotely. \n\n\nMore Information\n================\n\nProbably the best way to get started is to look at the documentation at\nhttp://pox.rtfd.io. Also see ``pox.tests`` for a set of scripts that demonstrate\nhow ``pox`` can be used to interact with the operating system. You can run the\ntest suite with ``python -m pox.tests``. All ``pox`` utilities\ncan be launched directly from an operating system terminal, using the ``pox``\nscript (or with ``python -m pox``). The source code is also generally well\ndocumented, so further questions may be resolved by inspecting the code\nitself. Please feel free to submit a ticket on github, or ask a\nquestion on stackoverflow (**@Mike McKerns**).\nIf you would like to share how you use ``pox`` in your work, please send an\nemail (to **mmckerns at uqfoundation dot org**).\n\n\nCitation\n========\n\nIf you use ``pox`` to do research that leads to publication, we ask that you\nacknowledge use of ``pox`` by citing the following in your publication::\n\n M.M. McKerns, L. Strand, T. Sullivan, A. Fang, M.A.G. Aivazis,\n \"Building a framework for predictive science\", Proceedings of\n the 10th Python in Science Conference, 2011;\n http://arxiv.org/pdf/1202.1056\n\n Michael McKerns and Michael Aivazis,\n \"pathos: a framework for heterogeneous computing\", 2010- ;\n https://uqfoundation.github.io/project/pathos\n\nPlease see https://uqfoundation.github.io/project/pathos or\nhttp://arxiv.org/pdf/1202.1056 for further information.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "utilities for filesystem exploration and automated builds",
"version": "0.3.5",
"project_urls": {
"Bug Tracker": "https://github.com/uqfoundation/pox/issues",
"Documentation": "http://pox.rtfd.io",
"Download": "https://pypi.org/project/pox/#files",
"Homepage": "https://github.com/uqfoundation/pox",
"Source Code": "https://github.com/uqfoundation/pox"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1d4c490d8f7825f38fa77bff188c568163f222d01f6c6d76f574429135edfc49",
"md5": "8779e593ab420383b63130666b20d5f5",
"sha256": "9e82bcc9e578b43e80a99cad80f0d8f44f4d424f0ee4ee8d4db27260a6aa365a"
},
"downloads": -1,
"filename": "pox-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8779e593ab420383b63130666b20d5f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 29492,
"upload_time": "2024-09-28T23:07:55",
"upload_time_iso_8601": "2024-09-28T23:07:55.621001Z",
"url": "https://files.pythonhosted.org/packages/1d/4c/490d8f7825f38fa77bff188c568163f222d01f6c6d76f574429135edfc49/pox-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2e0df2eb94b4d1358a60f3539a6abcbbd757fbcb78538fe8d4cfa49850356ccf",
"md5": "19b37199e356d9a0451bb834924fd41f",
"sha256": "8120ee4c94e950e6e0483e050a4f0e56076e590ba0a9add19524c254bd23c2d1"
},
"downloads": -1,
"filename": "pox-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "19b37199e356d9a0451bb834924fd41f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 119452,
"upload_time": "2024-09-28T23:07:57",
"upload_time_iso_8601": "2024-09-28T23:07:57.185595Z",
"url": "https://files.pythonhosted.org/packages/2e/0d/f2eb94b4d1358a60f3539a6abcbbd757fbcb78538fe8d4cfa49850356ccf/pox-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-28 23:07:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uqfoundation",
"github_project": "pox",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "pox"
}
JSON
