asyncinotify


Nameasyncinotify JSON
Version 4.0.6 PyPI version JSON
download
home_pageNone
SummaryA simple optionally-async python inotify library, focused on simplicity of use and operation, and leveraging modern Python features
upload_time2024-01-15 17:50:50
maintainerNone
docs_urlNone
authorNone
requires_python>= 3.6, < 4
licenseNone
keywords async inotify
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            asyncinotify
============

An async python inotify package.  Kept as simple and easy-to-understand as
possible, while still being flexible and powerful.  This is built on no external
dependencies, and works through ctypes in a very obvious fashion.

This depends on Python 3.6+ features, and will not work with prior versions.

This works without any other external dependencies.

The code is available on GitHub_ and the documentation is available on
ReadTheDocs_. The package itself is available on PyPi_.

Installation
------------

You know the drill::

  pip install asyncinotify

Usage
-----

The core of this package is ``asyncinotify.Inotify``.  Most important
Classes may be imported directly from the ``asyncinotify`` package.

.. code-block:: python

  from pathlib import Path
  from asyncinotify import Inotify, Mask
  import asyncio

  async def main():
      # Context manager to close the inotify handle after use
      with Inotify() as inotify:
          # Adding the watch can also be done outside of the context manager.
          # __enter__ doesn't actually do anything except return self.
          # This returns an asyncinotify.inotify.Watch instance
          inotify.add_watch('/tmp', Mask.ACCESS | Mask.MODIFY | Mask.OPEN | Mask.CREATE | Mask.DELETE | Mask.ATTRIB | Mask.CLOSE | Mask.MOVE | Mask.ONLYDIR)
          # Iterate events forever, yielding them one at a time
          async for event in inotify:
              # Events have a helpful __repr__.  They also have a reference to
              # their Watch instance.
              print(event)

              # the contained path may or may not be valid UTF-8.  See the note
              # below
              print(repr(event.path))

  asyncio.run(main())

This will asynchronously watch the /tmp directory and report events it
encounters.

This library also supports synchronous operation, using the
`asyncinotify.inotify.Inotify.sync_get`` method, or simply using
synchronous iteration.

Motivation
----------

There are a few different python inotify packages.  Most of them either have odd
conventions, expose too much of the underlying C API in a way that I personally
don't like, are badly documented, they work with paths in a non-idiomatic way,
are not asynchronous, or are overengineered compared to the API they are
wrapping.  I find that the last one is true for the majority of them.

I encourage everybody to read the `sources <GitHub_>`_ of this package.  They are
quite simple and easy to understand.

This library

* Works in a very simple way.  It does not have add-ons or extra features beyond
  presenting a very Python interface to the raw inotify functionality.

* Grabs events in bulk and caches them for minor performance gains.

* Leverages IntFlag for all masks and flags, allowing the user to use the
  features of IntFlag, such as seeing individual applied flags in the ``repr``,
  checking for flag set bits with ``in``.

* Exposes all paths via python's pathlib_

* Exposes all the functionality of inotify without depending on the user having
  to interact with any of the underlying mechanics of Inotify.  You should never
  have to touch the inotify or watch descriptors for any reason.

The primary motivation is that this is written to be a Python inotify module
that I would feel comfortable using.

.. _ospackage: https://docs.python.org/3/library/os.html#file-names-command-line-arguments-and-environment-variables
.. _surrogateescape: https://docs.python.org/3/library/codecs.html#surrogateescape
.. _GitHub: https://github.com/absperf/asyncinotify
.. _pathlib: https://docs.python.org/3/library/pathlib.html
.. _ReadTheDocs: https://asyncinotify.readthedocs.io/en/latest/
.. _PyPi: https://pypi.org/project/asyncinotify/

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "asyncinotify",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">= 3.6, < 4",
    "maintainer_email": null,
    "keywords": "async,inotify",
    "author": null,
    "author_email": "\"Taylor C. Richberger\" <tcr@absolute-performance.com>",
    "download_url": "https://files.pythonhosted.org/packages/c7/99/4e21607e4fdb9a2e40f22e08dd448be9dc92a6614c4431eaea1d8ee2067a/asyncinotify-4.0.6.tar.gz",
    "platform": null,
    "description": "asyncinotify\n============\n\nAn async python inotify package.  Kept as simple and easy-to-understand as\npossible, while still being flexible and powerful.  This is built on no external\ndependencies, and works through ctypes in a very obvious fashion.\n\nThis depends on Python 3.6+ features, and will not work with prior versions.\n\nThis works without any other external dependencies.\n\nThe code is available on GitHub_ and the documentation is available on\nReadTheDocs_. The package itself is available on PyPi_.\n\nInstallation\n------------\n\nYou know the drill::\n\n  pip install asyncinotify\n\nUsage\n-----\n\nThe core of this package is ``asyncinotify.Inotify``.  Most important\nClasses may be imported directly from the ``asyncinotify`` package.\n\n.. code-block:: python\n\n  from pathlib import Path\n  from asyncinotify import Inotify, Mask\n  import asyncio\n\n  async def main():\n      # Context manager to close the inotify handle after use\n      with Inotify() as inotify:\n          # Adding the watch can also be done outside of the context manager.\n          # __enter__ doesn't actually do anything except return self.\n          # This returns an asyncinotify.inotify.Watch instance\n          inotify.add_watch('/tmp', Mask.ACCESS | Mask.MODIFY | Mask.OPEN | Mask.CREATE | Mask.DELETE | Mask.ATTRIB | Mask.CLOSE | Mask.MOVE | Mask.ONLYDIR)\n          # Iterate events forever, yielding them one at a time\n          async for event in inotify:\n              # Events have a helpful __repr__.  They also have a reference to\n              # their Watch instance.\n              print(event)\n\n              # the contained path may or may not be valid UTF-8.  See the note\n              # below\n              print(repr(event.path))\n\n  asyncio.run(main())\n\nThis will asynchronously watch the /tmp directory and report events it\nencounters.\n\nThis library also supports synchronous operation, using the\n`asyncinotify.inotify.Inotify.sync_get`` method, or simply using\nsynchronous iteration.\n\nMotivation\n----------\n\nThere are a few different python inotify packages.  Most of them either have odd\nconventions, expose too much of the underlying C API in a way that I personally\ndon't like, are badly documented, they work with paths in a non-idiomatic way,\nare not asynchronous, or are overengineered compared to the API they are\nwrapping.  I find that the last one is true for the majority of them.\n\nI encourage everybody to read the `sources <GitHub_>`_ of this package.  They are\nquite simple and easy to understand.\n\nThis library\n\n* Works in a very simple way.  It does not have add-ons or extra features beyond\n  presenting a very Python interface to the raw inotify functionality.\n\n* Grabs events in bulk and caches them for minor performance gains.\n\n* Leverages IntFlag for all masks and flags, allowing the user to use the\n  features of IntFlag, such as seeing individual applied flags in the ``repr``,\n  checking for flag set bits with ``in``.\n\n* Exposes all paths via python's pathlib_\n\n* Exposes all the functionality of inotify without depending on the user having\n  to interact with any of the underlying mechanics of Inotify.  You should never\n  have to touch the inotify or watch descriptors for any reason.\n\nThe primary motivation is that this is written to be a Python inotify module\nthat I would feel comfortable using.\n\n.. _ospackage: https://docs.python.org/3/library/os.html#file-names-command-line-arguments-and-environment-variables\n.. _surrogateescape: https://docs.python.org/3/library/codecs.html#surrogateescape\n.. _GitHub: https://github.com/absperf/asyncinotify\n.. _pathlib: https://docs.python.org/3/library/pathlib.html\n.. _ReadTheDocs: https://asyncinotify.readthedocs.io/en/latest/\n.. _PyPi: https://pypi.org/project/asyncinotify/\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A simple optionally-async python inotify library, focused on simplicity of use and operation, and leveraging modern Python features",
    "version": "4.0.6",
    "project_urls": {
        "documentation": "https://asyncinotify.readthedocs.io/",
        "repository": "https://github.com/absperf/asyncinotify/"
    },
    "split_keywords": [
        "async",
        "inotify"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "0f94535771ce43201eb3b4c684812b2c4debc21a34e463872b2338555a49ce0d",
                "md5": "0851ad4b891134dfac35b8ecbacdbd85",
                "sha256": "f1b4e49d5e421692402a85ba9d7769d2e1ec0f0a15876cf6828dd3d5fb00ef22"
            },
            "downloads": -1,
            "filename": "asyncinotify-4.0.6-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0851ad4b891134dfac35b8ecbacdbd85",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": ">= 3.6, < 4",
            "size": 16798,
            "upload_time": "2024-01-15T17:50:48",
            "upload_time_iso_8601": "2024-01-15T17:50:48.862257Z",
            "url": "https://files.pythonhosted.org/packages/0f/94/535771ce43201eb3b4c684812b2c4debc21a34e463872b2338555a49ce0d/asyncinotify-4.0.6-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c7994e21607e4fdb9a2e40f22e08dd448be9dc92a6614c4431eaea1d8ee2067a",
                "md5": "6619e59e12979061157cf188ec8ccedf",
                "sha256": "c03fdb1a7dbb6bed8ede763e4e0ac224a2a3157bdc51e4ba3832588a3c29904d"
            },
            "downloads": -1,
            "filename": "asyncinotify-4.0.6.tar.gz",
            "has_sig": false,
            "md5_digest": "6619e59e12979061157cf188ec8ccedf",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">= 3.6, < 4",
            "size": 23913,
            "upload_time": "2024-01-15T17:50:50",
            "upload_time_iso_8601": "2024-01-15T17:50:50.554845Z",
            "url": "https://files.pythonhosted.org/packages/c7/99/4e21607e4fdb9a2e40f22e08dd448be9dc92a6614c4431eaea1d8ee2067a/asyncinotify-4.0.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-01-15 17:50:50",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "absperf",
    "github_project": "asyncinotify",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "asyncinotify"
}
        
Elapsed time: 0.16934s