Metadata-Version: 2.3
Name: ipctools
Version: 0.1.1
Summary: Inter-process communication tools.
Author: Narvin Singh
Author-email: Narvin Singh <Narvin.A.Singh@gmail.com>
License: Inter-process communication tools.
         Copyright (C) 2026  Narvin Singh
         
         This program 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 License, or
         (at your option) any later version.
         
         This program 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 the
         GNU General Public License for more details.
         
         You should have received a copy of the GNU General Public License
         along with this program.  If not, see <https://www.gnu.org/licenses/>.
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Dist: python-docs-theme~=2025.12 ; extra == 'doc'
Requires-Dist: sphinx~=9.1 ; extra == 'doc'
Requires-Python: >=3.12
Project-URL: Homepage, https://codeberg.org/ipctools
Project-URL: Repository, https://codeberg.org/ipctools
Project-URL: Bug Tracker, https://codeberg.org/ipctools/issues
Provides-Extra: doc
Description-Content-Type: text/x-rst

Ipctools
########

Ipctools is a library to facilitate inter-process communication.


Installation
************

.. code-block:: shell

   pip install ipctools

Usage
*****

The ``store`` API is used to get or set values in a key-value store. This store
is implemented as a temporary file on the system. The default file location may
be overridden with the ``IPCTOOLS_STORE`` environment variable.

Set, and get a value from the store.

.. code-block:: shell

    from ipctools import store

    store.set_value("my_key", "my_value")
    value = store.get_value("my_key")
    assert value == "my_value"

Setting a value updates it if exists.

.. code-block:: shell

    store.set_value("my_key", "my_value_1")
    store.set_value("my_key", "my_value_2")
    value = store.get_value("my_key")
    assert value == "my_value_2"

However, creating a value will fail if it already exits. You can perform leader
election across multiple processes by having each one try to set a value. Only
one process will succeed, so that one can be the leader.

.. code-block:: shell

    import os

    from ipctools import store

    is_leader = store.create_value("leader", str(os.getpid()))

Since the value of ``leader`` was set to the process ID of a single process,
any process can also determine who the leader is.

.. code-block:: shell

    def am_i_the_leader() -> bool:
        return store.get_value("leader") == str(os.getpid())

If mutliple processes try to set a value at the same time, some of them may
fail. You can try to set a value with retries.

.. code-block:: shell

    store.try_set_value("my_key", "my_value", retries=2)
