Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jwodder/inplace

In-place file processing in Python
https://github.com/jwodder/inplace

available-on-pypi file fileinput in-place inplace io open python redirection sed tempfile tmpfile

Last synced: 14 days ago
JSON representation

In-place file processing in Python

Awesome Lists containing this project

README 

        
|repostatus| |ci-status| |coverage| |pyversions| |conda| |license|



.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg

    :target: https://www.repostatus.org/#active

    :alt: Project Status: Active - The project has reached a stable, usable

          state and is being actively developed.



.. |ci-status| image:: https://github.com/jwodder/inplace/actions/workflows/test.yml/badge.svg

    :target: https://github.com/jwodder/inplace/actions/workflows/test.yml

    :alt: CI Status



.. |coverage| image:: https://codecov.io/gh/jwodder/inplace/branch/master/graph/badge.svg

    :target: https://codecov.io/gh/jwodder/inplace



.. |pyversions| image:: https://img.shields.io/pypi/pyversions/in_place.svg

    :target: https://pypi.org/project/in_place



.. |conda| image:: https://img.shields.io/conda/vn/conda-forge/in_place.svg

    :target: https://anaconda.org/conda-forge/in_place

    :alt: Conda Version



.. |license| image:: https://img.shields.io/github/license/jwodder/inplace.svg?maxAge=2592000

    :target: https://opensource.org/licenses/MIT

    :alt: MIT License



`GitHub `_

| `PyPI `_

| `Issues `_

| `Changelog `_



The ``in_place`` module provides an ``InPlace`` class for reading & writing a

file "in-place": data that you write ends up at the same filepath that you read

from, and ``in_place`` takes care of all the necessary mucking about with

temporary files for you.



For example, given the file ``somefile.txt``::



    'Twas brillig, and the slithy toves

        Did gyre and gimble in the wabe;

    All mimsy were the borogoves,

        And the mome raths outgrabe.



and the program ``disemvowel.py``:



.. code:: python



    import in_place



    with in_place.InPlace("somefile.txt") as fp:

        for line in fp:

            fp.write("".join(c for c in line if c not in "AEIOUaeiou"))



after running the program, ``somefile.txt`` will have been edited in place,

reducing it to just::



    'Tws brllg, nd th slthy tvs

        Dd gyr nd gmbl n th wb;

    ll mmsy wr th brgvs,

        nd th mm rths tgrb.



and no sign of those pesky vowels remains!  If you want a sign of those pesky

vowels to remain, you can instead save the file's original contents in, say,

``somefile.txt~`` by constructing the filehandle with:



.. code:: python



    in_place.InPlace("somefile.txt", backup_ext="~")



or save to ``someotherfile.txt`` with:



.. code:: python



    in_place.InPlace("somefile.txt", backup="someotherfile.txt")



Compared to the in-place filtering implemented by the Python standard library's

|fileinput|_ module, ``in_place`` offers the following benefits:



- Instead of hijacking ``sys.stdout``, a new filehandle is returned for

  writing.

- The filehandle supports all of the standard I/O methods, not just

  ``readline()``.

- There are options for setting the encoding, encoding error handling, and

  newline policy for opening the file, along with support for opening files in

  binary mode, and these options apply to both input and output.

- The complete filename of the backup file can be specified; you aren't

  constrained to just adding an extension.

- When used as a context manager, ``in_place`` will restore the original file

  if an exception occurs.

- The creation of temporary files won't silently clobber innocent bystander

  files.



.. |fileinput| replace:: ``fileinput``

.. _fileinput: https://docs.python.org/3/library/fileinput.html



Installation

============

``in_place`` requires Python 3.8 or higher.  Just use `pip

`_ for Python 3 (You have pip, right?) to install it::



    python3 -m pip install in_place



Basic Usage

===========

``in_place`` provides a single class, ``InPlace``.  Its constructor takes the

following arguments:



``name=`` (required)

   The path to the file to open & edit in-place



``mode=<"b"|"t"|None>``

   Whether to operate on the file in binary or text mode.  If ``mode`` is

   ``"b"``, the file will be opened in binary mode, and data will be read &

   written as ``bytes`` objects.  If ``mode`` is ``"t"`` or ``None`` (the

   default), the file will be opened in text mode, and data will be read &

   written as ``str`` objects.



``backup=``

   If set, the original contents of the file will be saved to the given path

   when the instance is closed.  ``backup`` cannot be set to the empty string.



``backup_ext=``

   If set, the path to the backup file will be created by appending

   ``backup_ext`` to the original file path.



   ``backup`` and ``backup_ext`` are mutually exclusive.  ``backup_ext`` cannot

   be set to the empty string.



``**kwargs``

   Any additional keyword arguments (such as ``encoding``, ``errors``, and

   ``newline``) will be forwarded to ``open()`` when opening both the input and

   output file streams.



``name``, ``backup``, and ``backup_ext`` can be ``str``, filesystem-encoded

``bytes``, or path-like objects.



``InPlace`` instances act as read-write filehandles with the usual filehandle

attributes, specifically::



    __iter__()              __next__()              closed

    flush()                 name                    read()

    read1() *               readinto() *            readinto1() *

    readline()              readlines()             write()

    writelines()



    * binary mode only



``InPlace`` instances also feature the following new or modified attributes:



``close()``

   Close filehandles and move files to their final destinations.  If called

   after the filehandle has already been closed, ``close()`` does nothing.



   Be sure to always close your instances when you're done with them by calling

   ``close()`` or ``rollback()`` either explicitly or implicitly (i.e., via use

   as a context manager).



``rollback()``

   Like ``close()``, but discard the output data (keeping the original file

   intact) instead of replacing the original file with it



``__enter__()``, ``__exit__()``

   When an ``InPlace`` instance is used as a context manager, on exiting the

   context, the instance will be either closed (if all went well) or rolled

   back (if an exception occurred).  ``InPlace`` context managers are not

   reusable_ but are reentrant_ (as long as no further operations are performed

   after the innermost context ends).



``input``

   The actual filehandle that data is read from, in case you need to access it

   directly



``output``

   The actual filehandle that data is written to, in case you need to access it

   directly



.. _reentrant: https://docs.python.org/3/library/contextlib.html#reentrant-cms

.. _reusable: https://docs.python.org/3/library/contextlib.html#reusable-context-managers