Metadata-Version: 2.4
Name: mbanucu-pyexiftool
Version: 0.6.2
Summary: PyExifTool fork with server/client support
Home-page: https://github.com/MBanucu/pyexiftool
Author: MBanucu
Author-email: 
License: GPLv3+/BSD
Project-URL: Source, https://github.com/MBanucu/pyexiftool
Project-URL: Tracker, https://github.com/MBanucu/pyexiftool/issues
Keywords: exiftool image exif metadata photo video photography
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: COPYING.BSD
License-File: COPYING.GPL
Provides-Extra: json
Requires-Dist: ujson; extra == "json"
Requires-Dist: simplejson; extra == "json"
Requires-Dist: orjson; extra == "json"
Provides-Extra: test
Requires-Dist: packaging; extra == "test"
Provides-Extra: docs
Requires-Dist: packaging; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

**********
PyExifTool
**********



.. image:: https://img.shields.io/pypi/v/mbanucu-pyexiftool.svg
	:target: https://pypi.org/project/mbanucu-pyexiftool/
	:alt: PyPI Version

.. image:: https://img.shields.io/pypi/pyversions/mbanucu-pyexiftool.svg
	:target: https://pypi.org/project/mbanucu-pyexiftool/
	:alt: Supported Python Versions



.. DESCRIPTION_START

.. BLURB_START

PyExifTool is a Python library to communicate with an instance of
`Phil Harvey's ExifTool`_ command-line application.

.. _Phil Harvey's ExifTool: https://exiftool.org/


.. BLURB_END

The library provides the class ``exiftool.ExifTool`` that runs the command-line
tool in batch mode and features methods to send commands to that
program, including methods to extract meta-information from one or
more image files.  Since ``exiftool`` is run in batch mode, only a
single instance needs to be launched and can be reused for many
queries.  This is much more efficient than launching a separate
process for every single query.


.. DESCRIPTION_END

.. contents::
	:depth: 2
	:backlinks: none

Example Usage
=============

Simple example: ::

	import exiftool

	files = ["a.jpg", "b.png", "c.tif"]
	with exiftool.ExifToolHelper() as et:
	    metadata = et.get_metadata(files)
	    for d in metadata:
	        print("{:20.20} {:20.20}".format(d["SourceFile"],
	                                         d["EXIF:DateTimeOriginal"]))

Refer to documentation for more `Examples and Quick Start Guide`_

.. _`Examples and Quick Start Guide`: http://sylikc.github.io/pyexiftool/examples.html


.. INSTALLATION_START

Getting PyExifTool
==================

PyPI
------------

Easiest: Install a version from `mbanucu-pyexiftool on PyPI`_

::

    python -m pip install -U mbanucu-pyexiftool

.. _mbanucu-pyexiftool on PyPI: https://pypi.org/project/mbanucu-pyexiftool/


From Source
------------

#. Check out the source code from the github repository

	* ``git clone https://github.com/MBanucu/pyexiftool.git``
	* Alternatively, you can download a tarball_.

#. Run setup.py to install the module from source

	* ``python setup.py install [--user|--prefix=<installation-prefix>]``


.. _tarball: https://github.com/MBanucu/pyexiftool/tarball/master


PyExifTool Dependencies
=======================

Python
------

PyExifTool runs on **Python 3.6+**.  (If you need Python 2.6 support,
please use version v0.4.x).  PyExifTool has been tested on Windows and
Linux, and probably also runs on other Unix-like platforms.

Phil Harvey's exiftool
----------------------

For PyExifTool to function, ``exiftool`` command-line tool must exist on
the system.  If ``exiftool`` is not on the ``PATH``, you can specify the full
pathname to it by using ``ExifTool(executable=<full path>)``.

PyExifTool requires a **minimum version of 12.15** (which was the first
production version of exiftool featuring the options to allow exit status
checks used in conjuction with ``-echo3`` and ``-echo4`` parameters).

To check your ``exiftool`` version:

::

    exiftool -ver


Windows/Mac
^^^^^^^^^^^

Windows/Mac users can download the latest version of exiftool:

::

    https://exiftool.org

Linux
^^^^^

Most current Linux distributions have a package which will install ``exiftool``.
Unfortunately, some do not have the minimum required version, in which case you
will have to `build from source`_.

* Ubuntu
  ::

    sudo apt install libimage-exiftool-perl

* CentOS/RHEL
  ::

    yum install perl-Image-ExifTool

.. _build from source: https://exiftool.org/install.html#Unix


.. INSTALLATION_END


Documentation
=============

The current documentation is available at `sylikc.github.io`_ or `MBanucu on GitHub`_.

::

    http://sylikc.github.io/pyexiftool/

.. _sylikc.github.io: http://sylikc.github.io/pyexiftool/
.. _MBanucu on GitHub: https://github.com/MBanucu/pyexiftool


Package Structure
-----------------

.. DESIGN_INFO_START

PyExifTool was designed with flexibility and extensibility in mind.  The library consists of a few classes, each with increasingly more features.

The base ``ExifTool`` class contains the core functionality exposed in the most rudimentary way, and each successive class inherits and adds functionality.

.. DESIGN_INFO_END

.. DESIGN_CLASS_START

* ``exiftool.ExifTool`` is the base class with core logic to interface with PH's ExifTool process.
  It contains only the core features with no extra fluff.
  The main methods provided are ``execute()`` and ``execute_json()`` which allows direct interaction with the underlying exiftool process.

  * The API is considered stable and should not change much with future releases.

* ``exiftool.ExifToolHelper`` exposes some of the most commonly used functionality.  It overloads
  some inherited functions to turn common errors into warnings and adds logic to make
  ``exiftool.ExifTool`` easier to use.
  For example, ``ExifToolHelper`` provides wrapper functions to get metadata, and auto-starts the exiftool instance if it's not running (instead of raising an Exception).
  ``ExifToolHelper`` demonstrates how to extend ``ExifTool`` to your liking if your project demands customizations not directly provided by ``ExifTool``.

  * More methods may be added and/or slight API tweaks may occur with future releases.

* ``exiftool.ExifToolAlpha`` further extends the ``ExifToolHelper`` and includes some community-contributed not-very-well-tested methods.
  These methods were formerly added ad-hoc by various community contributors, but no longer stand up to the rigor of the current design.
  ``ExifToolAlpha`` is *not* up to the rigorous testing standard of both
  ``ExifTool`` or ``ExifToolHelper``.  There may be old, buggy, or defunct code.

  * This is the least polished of the classes and functionality/API may be changed/added/removed on any release.

  * **NOTE: The methods exposed may be changed/removed at any time.**

  * If you are using any of these methods in your project, please `Submit an Issue`_ to start a discussion on making those functions more robust, and making their way into ``ExifToolHelper``.
    (Think of ``ExifToolAlpha`` as ideas on how to extend ``ExifTool``, where new functionality which may one day make it into the ``ExifToolHelper`` class.)

.. _Submit an Issue: https://github.com/MBanucu/pyexiftool/issues


.. DESIGN_CLASS_END


Server / Client Mode
--------------------

PyExifTool provides a TCP server mode that allows multiple processes or
threads to share a single ``exiftool`` subprocess.  This avoids the
overhead of starting a new subprocess per client and is essential when
multiple processes must not concurrently write to the same filesystem.

The server listens on a TCP socket and accepts JSON-RPC-like requests.
The client provides the same API as ``exiftool.ExifToolHelper``,
making it a drop-in replacement.

* ``exiftool.ExifToolServer`` wraps an ``ExifToolHelper`` instance and
  exposes it over TCP.  It auto-shuts down after an idle timeout.

* ``exiftool.ExifToolClient`` connects to a running server and proxies
  all calls to it.

Example::

    import exiftool

    # Start a server
    server = exiftool.ExifToolServer()
    port = server.start()

    # Connect a client from another process (or the same one)
    with exiftool.ExifToolClient(port=port) as client:
        metadata = client.get_metadata("file.jpg")

    # Servers auto-shutdown after 60s idle; stop explicitly:
    server.stop()

Auto-discovery via a well-known port file (``pyexiftool-server.json``
in the temp directory) is also supported::

    # Process A: start server (uses default port file)
    server = exiftool.ExifToolServer()
    server.start()

    # Process B: auto-discover
    client = exiftool.ExifToolClient()
    print(client.execute("-ver"))

    # Or spawn a server as a background subprocess:
    port = exiftool.spawn_server()
    print(f"Server on port {port}")

Discovered server port from a running server::

    port = exiftool.find_server()
    if port:
        print(f"Found server on port {port}")


Brief History
=============

.. HISTORY_START

PyExifTool was originally developed by `Sven Marnach`_ in 2012 to answer a
stackoverflow question `Call exiftool from a python script?`_.  Over time,
Sven refined the code, added tests, documentation, and a slew of improvements.
While PyExifTool gained popularity, Sven `never intended to maintain it`_ as
an active project.  The `original repository`_ was last updated in 2014.

Over the years, numerous issues were filed and several PRs were opened on the
stagnant repository.  In early 2019, `Martin Čarnogurský`_ created a
`PyPI release`_ from the 2014 code with some minor updates.  Coincidentally in
mid 2019, `Kevin M (sylikc)`_ forked the original repository and started merging
the PR and issues which were reported on Sven's issues/PR page.

In late 2019 and early 2020 there was a discussion started to
`Provide visibility for an active fork`_.  There was a conversation to
transfer ownership of the original repository, have a coordinated plan to
communicate to PyExifTool users, amongst other things, but it never materialized.

Kevin M (sylikc) made the first release to the PyPI repository in early 2021.
At the same time, discussions were started, revolving around
`Deprecating Python 2.x compatibility`_ and `refactoring the code and classes`_.

The latest version is the result of all of those discussions, designs,
and development.  Special thanks to the community contributions, especially
`Jan Philip Göpfert`_, `Seth P`_, and `Kolen Cheung`_.

.. _Sven Marnach: https://github.com/smarnach/pyexiftool
.. _Call exiftool from a python script?: https://stackoverflow.com/questions/10075115/call-exiftool-from-a-python-script/10075210#10075210
.. _never intended to maintain it: https://github.com/smarnach/pyexiftool/pull/31#issuecomment-569238073
.. _original repository: https://github.com/smarnach/pyexiftool
.. _Martin Čarnogurský: https://github.com/RootLUG
.. _PyPI release: https://pypi.org/project/PyExifTool/0.1.1/#history
.. _Kevin M (sylikc): https://github.com/sylikc
.. _Provide visibility for an active fork: https://github.com/smarnach/pyexiftool/pull/31
.. _Deprecating Python 2.x compatibility: https://github.com/sylikc/pyexiftool/discussions/9
.. _refactoring the code and classes: https://github.com/sylikc/pyexiftool/discussions/10
.. _Jan Philip Göpfert: https://github.com/jangop
.. _Seth P: https://github.com/csparker247
.. _Kolen Cheung: https://github.com/ickc


.. HISTORY_END

Licence
=======

.. LICENSE_START

PyExifTool is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the licence, or
(at your option) any later version, or the BSD licence.

PyExifTool is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See ``LICENSE`` for more details.


.. LICENSE_END
