findx - an extended ``find`` command.
=====================================
.. image:: https://travis-ci.org/drmikehenry/findx.svg
:target: https://travis-ci.org/drmikehenry/findx
.. image:: https://img.shields.io/pypi/v/findx.svg
:target: https://pypi.python.org/pypi/findx
.. image:: https://img.shields.io/pypi/status/findx.svg
:target: https://pypi.python.org/pypi/findx
.. image:: https://img.shields.io/pypi/pyversions/findx.svg
:target: https://pypi.python.org/pypi/findx/
Overview
--------
``findx`` is an extended version of the Unix ``find`` command written in the
Python language as a wrapper around ``find`` and other Unix tools. ``find`` is
a very powerful tool, but by itself there are a large number of arguments
required for a typical invocation. ``findx`` provides convenient shortcuts for
invoking ``find`` without so much typing.
As a quick example, imagine using ``find``, ``xargs`` and ``grep`` to search
through a tree of files. A simple invocation might be::
find -type f | xargs grep PATTERN
But the above invocation won't correctly handle file with spaces or unusual
characters; handling that grows the command to::
find -type f -print0 | xargs -0 grep PATTERN
Filenames are handled correctly now, but the command probably searches through
some uninteresting files. It also misses on a couple of boundary cases. You'd
probably like to include ``xargs --no-run-if-empty`` to ensure ``grep`` isn't
invoked when no files are found; you might want to follow symbolic links as well
as files; and you might want to skip over ``.git`` directories (for example).
Adding those into the above command grows things considerably::
find -L -name .git -prune -o -type f -print0 |
xargs -0 --no-run-if-empty grep PATTERN
After excluding additional files and directories and perhaps adding
``--color=auto`` to the ``grep`` invocation, things are getting out of hand.
``findx`` exists to make such invocations simpler. First, ``findx`` knows about
the need for ``-print0`` and ``xargs -0 --no-run-if-empty``; using ``:`` implies
all of the standard protocol for using ``xargs`` correctly, reducing the above
to::
findx -L -name .git -prune -o -type f : grep PATTERN
Standard paths to ignore are requested via ``-stdx``::
findx -L -stdx -type f : grep PATTERN
Following symlinks to files and producing only files is another common
requirement; the switch ``-ffx`` implies finding files (following symlinks)
while excluding a predefined set of directories and files::
findx -ffx : grep PATTERN
Piping filenames into ``grep`` is such a common pattern that the ``-ffg`` switch
is the same as ``-ffx : grep``, reducing things to::
findx -ffg PATTERN
In addition, ``ffx`` and ``ffg`` are to additional entry points into ``findx``
that reduce things even further::
ffx = findx -ffx
ffg = findx -ffg
In the most common case, searching a file tree thus reduces to::
ffg PATTERN
See ``findx --help`` or read the top of ``findx.py`` for more details.
Installation
------------
From PyPI, installation is the usual::
pip install findx
From the source tree, install via::
python setup.py install
Running the tests
-----------------
Install any development requirements::
pip install -r dev-requirements.txt
Run tests via pytest::
pytest
Changes
-------
See CHANGES.rst for a history of changes.
License
-------
``findx`` is distributed under the terms of the MIT license; see LICENSE.rst
for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/drmikehenry/findx",
"name": "findx",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": null,
"keywords": "extended, find, file, search",
"author": "Michael Henry",
"author_email": "drmikehenry@drmikehenry.com",
"download_url": "https://files.pythonhosted.org/packages/74/0f/b245fc9df504f9b7eb2ba98cd5290650695da54970b38cb9a6eab50d5851/findx-0.11.0.tar.gz",
"platform": null,
"description": "findx - an extended ``find`` command.\n=====================================\n\n.. image:: https://travis-ci.org/drmikehenry/findx.svg\n :target: https://travis-ci.org/drmikehenry/findx\n\n.. image:: https://img.shields.io/pypi/v/findx.svg\n :target: https://pypi.python.org/pypi/findx\n\n.. image:: https://img.shields.io/pypi/status/findx.svg\n :target: https://pypi.python.org/pypi/findx\n\n.. image:: https://img.shields.io/pypi/pyversions/findx.svg\n :target: https://pypi.python.org/pypi/findx/\n\nOverview\n--------\n\n``findx`` is an extended version of the Unix ``find`` command written in the\nPython language as a wrapper around ``find`` and other Unix tools. ``find`` is\na very powerful tool, but by itself there are a large number of arguments\nrequired for a typical invocation. ``findx`` provides convenient shortcuts for\ninvoking ``find`` without so much typing.\n\nAs a quick example, imagine using ``find``, ``xargs`` and ``grep`` to search\nthrough a tree of files. A simple invocation might be::\n\n find -type f | xargs grep PATTERN\n\nBut the above invocation won't correctly handle file with spaces or unusual\ncharacters; handling that grows the command to::\n\n find -type f -print0 | xargs -0 grep PATTERN\n\nFilenames are handled correctly now, but the command probably searches through\nsome uninteresting files. It also misses on a couple of boundary cases. You'd\nprobably like to include ``xargs --no-run-if-empty`` to ensure ``grep`` isn't\ninvoked when no files are found; you might want to follow symbolic links as well\nas files; and you might want to skip over ``.git`` directories (for example).\nAdding those into the above command grows things considerably::\n\n find -L -name .git -prune -o -type f -print0 |\n xargs -0 --no-run-if-empty grep PATTERN\n\nAfter excluding additional files and directories and perhaps adding\n``--color=auto`` to the ``grep`` invocation, things are getting out of hand.\n``findx`` exists to make such invocations simpler. First, ``findx`` knows about\nthe need for ``-print0`` and ``xargs -0 --no-run-if-empty``; using ``:`` implies\nall of the standard protocol for using ``xargs`` correctly, reducing the above\nto::\n\n findx -L -name .git -prune -o -type f : grep PATTERN\n\nStandard paths to ignore are requested via ``-stdx``::\n\n findx -L -stdx -type f : grep PATTERN\n\nFollowing symlinks to files and producing only files is another common\nrequirement; the switch ``-ffx`` implies finding files (following symlinks)\nwhile excluding a predefined set of directories and files::\n\n findx -ffx : grep PATTERN\n\nPiping filenames into ``grep`` is such a common pattern that the ``-ffg`` switch\nis the same as ``-ffx : grep``, reducing things to::\n\n findx -ffg PATTERN\n\nIn addition, ``ffx`` and ``ffg`` are to additional entry points into ``findx``\nthat reduce things even further::\n\n ffx = findx -ffx\n ffg = findx -ffg\n\nIn the most common case, searching a file tree thus reduces to::\n\n ffg PATTERN\n\nSee ``findx --help`` or read the top of ``findx.py`` for more details.\n\nInstallation\n------------\n\nFrom PyPI, installation is the usual::\n\n pip install findx\n\nFrom the source tree, install via::\n\n python setup.py install\n\nRunning the tests\n-----------------\n\nInstall any development requirements::\n\n pip install -r dev-requirements.txt\n\nRun tests via pytest::\n\n pytest\n\nChanges\n-------\n\nSee CHANGES.rst for a history of changes.\n\nLicense\n-------\n\n``findx`` is distributed under the terms of the MIT license; see LICENSE.rst\nfor details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "``findx``, an extended ``find`` command.",
"version": "0.11.0",
"project_urls": {
"Homepage": "https://github.com/drmikehenry/findx",
"Repository": "https://github.com/drmikehenry/findx"
},
"split_keywords": [
"extended",
" find",
" file",
" search"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "33e405a425b15520b5e6cd18e3c6d4a71a938b16ce4532e2698b6011d562583a",
"md5": "3f0b0f96877f42696b414c13912277bb",
"sha256": "20af4f09729fbb48020108a6eab3e5b2907796de3d2186621f3a673748859ca1"
},
"downloads": -1,
"filename": "findx-0.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f0b0f96877f42696b414c13912277bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 17482,
"upload_time": "2024-05-27T20:54:26",
"upload_time_iso_8601": "2024-05-27T20:54:26.861788Z",
"url": "https://files.pythonhosted.org/packages/33/e4/05a425b15520b5e6cd18e3c6d4a71a938b16ce4532e2698b6011d562583a/findx-0.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "740fb245fc9df504f9b7eb2ba98cd5290650695da54970b38cb9a6eab50d5851",
"md5": "c591ae3b98904b1b91f89ed23f9e0680",
"sha256": "a8942e42aa7565e4b1b013188159796cf89bb10d0be5edada346d45cc8633e67"
},
"downloads": -1,
"filename": "findx-0.11.0.tar.gz",
"has_sig": false,
"md5_digest": "c591ae3b98904b1b91f89ed23f9e0680",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 50416,
"upload_time": "2024-05-27T20:54:30",
"upload_time_iso_8601": "2024-05-27T20:54:30.917184Z",
"url": "https://files.pythonhosted.org/packages/74/0f/b245fc9df504f9b7eb2ba98cd5290650695da54970b38cb9a6eab50d5851/findx-0.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-27 20:54:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "drmikehenry",
"github_project": "findx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "findx"
}
JSON
