Threema Gateway API
===================
**threema-gateway** is a Python 3 module for the Threema gateway service.
This API can be used to send and receive text messages to and from any Threema
user.
Note
****
On machines where Python 3 is not the default Python runtime, you should
use ``pip3`` instead of ``pip``.
Prerequisites
*************
.. code-block:: bash
$ sudo apt-get install python3 python3-pip
We recommend using `venv`_ to create an isolated Python environment:
.. code-block:: bash
$ pyvenv venv
You can switch into the created virtual environment *venv* by running
this command:
.. code-block:: bash
$ source venv/bin/activate
While the virtual environment is active, all packages installed using
``pip`` will be installed into this environment.
To deactivate the virtual environment, just run:
.. code-block:: bash
$ deactivate
If you want easier handling of your virtualenvs, you might also want to
take a look at `virtualenvwrapper`_.
Installation
------------
If you are using a virtual environment, activate it first.
Install the module by running:
.. code-block:: bash
$ pip install threema.gateway
The dependency ``libnacl`` will be installed automatically. However, you
may need to install `libsodium`_ for ``libnacl`` to work.
Command Line Usage
******************
The script ``threema-gateway`` provides a command line interface for
the Threema gateway. Run the following command to see usage information:
.. code-block:: bash
$ threema-gateway --help
Gateway API Endpoint
--------------------
The default Gateway API Endpoint URL used is https://msgapi.threema.ch/.
If you are a Threema OnPrem customer or have another reason to use a different
Gateway API Endpoint, you may override the URL as follows:
.. code-block:: bash
$ export GATEWAY_API_URL=https://onprem.myinstance.tld/msgapi
Any following calls to ``threema-gateway`` will then use the supplied Gateway
API Endpoint URL.
Examples
********
You can find a few example scripts in the ``examples/`` directory.
Note that most of them need to be adjusted to at least add your gateway ID
credentials before they run successfully.
Feature Levels
**************
+---------+--------+----------------+---------+--------+-----------+
| Level | Text | Capabilities | Image | File | Credits |
+=========+========+================+=========+========+===========+
| 1 | X | | | | |
+---------+--------+----------------+---------+--------+-----------+
| 2 | X | X | X | X | |
+---------+--------+----------------+---------+--------+-----------+
| 3 | X | X | X | X | X |
+---------+--------+----------------+---------+--------+-----------+
You can see the implemented feature level by invoking the following
command:
.. code-block:: bash
$ threema-gateway version
Contributing
************
If you want to contribute to this project, you should install the
optional ``dev`` requirements of the project in an editable environment:
.. code-block:: bash
$ git clone https://github.com/threema-ch/threema-msgapi-sdk-python.git
$ cd threema-msgapi-sdk-python
$ pip install -e .[dev]
Before creating a pull request, it is recommended to run the following
commands to check for code style violations (``flake8``), optimise
imports (``isort``) and run the project's tests:
.. code-block:: bash
$ flake8 .
$ isort .
$ py.test
You should also run the type checker that might catch some additional bugs:
.. code-block:: bash
$ mypy setup.py tests examples threema
.. _asyncio: https://docs.python.org/3/library/asyncio.html
.. _venv: https://docs.python.org/3/library/venv.html
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/
.. _libsodium: https://download.libsodium.org/doc/installation/index.html
Changelog
*********
`8.0.0`_ (2024-08-21)
---------------------
- Add support for Python 3.10/3.11/3.12
- Drop support for Python versions below 3.8
- Bump dependencies
- Add `caption` to file message and to the CLI
- Add an optional parameter to the CLI for `send-simple` and `send-e2e` to allow
passing the text as an argument instead from stdin.
- Make the random padding spec compliant
- Add an optional environment variable `GATEWAY_API_URL` to override the Gateway
API Endpoint URL
`7.0.1`_ (2023-02-21)
---------------------
- Fix parsing of unknown reception capabilities
- Add new `ReceptionCapability` items
- Remove `ReceptionCapabilitiesError` (breaking)
`6.0.0`_ (2022-06-13)
---------------------
General:
- Add support for Python 3.10
- Drop support for Python versions below 3.7
- Major dependencies bump to increase compatibility with other packages
- Updated all tests to work with the newest dependencies
- Changed CLI syntax: All commands are now `dash-case` instead of `snake_case`,
e.g. the `send_e2e` command is now called `send-e2e`.
`5.0.0`_ (2021-05-17)
---------------------
- Add custom session and session arguments to `Connection` (#55, #56)
- Remove the `fingerprint` and `verify_fingerprint` arguments, see #55 for a
detailed explanation and how to achieve pinning
`4.0.0`_ (2021-01-23)
---------------------
General:
- Drop support for Python versions below 3.6.1.
- Remove `ReceiptType.user_ack` after deprecation. Use
`ReceiptType.user_acknowledge` instead.
- Simplify `util.aio_run`. It does not allow for passing a specific event loop
or closing the event loop on completion any longer.
- Rename `util.aio_run_proxy_decorator` to `aio_run_proxy`. It now always
creates the class instance within a running event loop.
Client:
- In async mode, creation of the `Connection` instance must now be done within
an `async` function.
- If you have used a `with` context manager block in async mode before, you
must now do this within an `async with` asynchronous context manager. No
change is required in blocking mode.
- `Connection.close` is now an async function.
Server:
- The callback server has been refactored and the `AbstractCallback` class has
been removed for more flexibility and control of the underlying
`aiohttp <https://docs.aiohttp.org>`_ server. Take a look at
`examples/callback.py` on how to use it.
- The callback server CLI has been removed because it was redundant. The
example provides the same functionality.
`3.1.0`_ (2020-04-21)
---------------------
- Add video message
- Fix slightly off calculation of image byte length
`3.0.6`_ (2017-09-22)
---------------------
- Migrate to aiohttp2
`3.0.5`_ (2017-07-25)
---------------------
- Fix to handle new `libnacl <https://github.com/saltstack/libnacl/pull/91>`_
exceptions.
`3.0.4`_ (2017-05-23)
---------------------
- Fix CLI
`3.0.2`_ (2017-05-12)
---------------------
- Initial publication on PyPI
.. _8.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v7.0.1...v8.0.0
.. _7.0.1: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v6.0.0...v7.0.1
.. _6.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v5.0.0...v6.0.0
.. _5.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v4.0.0...v5.0.0
.. _4.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.1.0...v4.0.0
.. _3.1.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.6...v3.1.0
.. _3.0.6: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.5...v3.0.6
.. _3.0.5: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.4...v3.0.5
.. _3.0.4: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.2...v3.0.4
.. _3.0.2: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/e982c74cbe564c76cc58322d3154916ee7f6863b...v3.0.2
Raw data
{
"_id": null,
"home_page": "https://gateway.threema.ch/",
"name": "threema.gateway",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "threema gateway service sdk api",
"author": "Lennart Grahl",
"author_email": "lennart.grahl@threema.ch",
"download_url": "https://files.pythonhosted.org/packages/7d/ed/3566a018210cebc1676755eb039367ca3298cd57a93adcd3491251b81f54/threema_gateway-8.0.0.tar.gz",
"platform": null,
"description": "Threema Gateway API\n===================\n\n**threema-gateway** is a Python 3 module for the Threema gateway service.\nThis API can be used to send and receive text messages to and from any Threema\nuser.\n\nNote\n****\n\nOn machines where Python 3 is not the default Python runtime, you should\nuse ``pip3`` instead of ``pip``.\n\nPrerequisites\n*************\n\n.. code-block:: bash\n\n $ sudo apt-get install python3 python3-pip\n\nWe recommend using `venv`_ to create an isolated Python environment:\n\n.. code-block:: bash\n\n $ pyvenv venv\n\nYou can switch into the created virtual environment *venv* by running\nthis command:\n\n.. code-block:: bash\n\n $ source venv/bin/activate\n\nWhile the virtual environment is active, all packages installed using\n``pip`` will be installed into this environment.\n\nTo deactivate the virtual environment, just run:\n\n.. code-block:: bash\n\n $ deactivate\n\nIf you want easier handling of your virtualenvs, you might also want to\ntake a look at `virtualenvwrapper`_.\n\nInstallation\n------------\n\nIf you are using a virtual environment, activate it first.\n\nInstall the module by running:\n\n.. code-block:: bash\n\n $ pip install threema.gateway\n\nThe dependency ``libnacl`` will be installed automatically. However, you\nmay need to install `libsodium`_ for ``libnacl`` to work.\n\nCommand Line Usage\n******************\n\nThe script ``threema-gateway`` provides a command line interface for\nthe Threema gateway. Run the following command to see usage information:\n\n.. code-block:: bash\n\n $ threema-gateway --help\n\nGateway API Endpoint\n--------------------\n\nThe default Gateway API Endpoint URL used is https://msgapi.threema.ch/.\n\nIf you are a Threema OnPrem customer or have another reason to use a different\nGateway API Endpoint, you may override the URL as follows:\n\n.. code-block:: bash\n\n $ export GATEWAY_API_URL=https://onprem.myinstance.tld/msgapi\n\nAny following calls to ``threema-gateway`` will then use the supplied Gateway\nAPI Endpoint URL.\n\nExamples\n********\n\nYou can find a few example scripts in the ``examples/`` directory.\n\nNote that most of them need to be adjusted to at least add your gateway ID\ncredentials before they run successfully.\n\nFeature Levels\n**************\n\n+---------+--------+----------------+---------+--------+-----------+\n| Level | Text | Capabilities | Image | File | Credits |\n+=========+========+================+=========+========+===========+\n| 1 | X | | | | |\n+---------+--------+----------------+---------+--------+-----------+\n| 2 | X | X | X | X | |\n+---------+--------+----------------+---------+--------+-----------+\n| 3 | X | X | X | X | X |\n+---------+--------+----------------+---------+--------+-----------+\n\nYou can see the implemented feature level by invoking the following\ncommand:\n\n.. code-block:: bash\n\n $ threema-gateway version\n\nContributing\n************\n\nIf you want to contribute to this project, you should install the\noptional ``dev`` requirements of the project in an editable environment:\n\n.. code-block:: bash\n\n $ git clone https://github.com/threema-ch/threema-msgapi-sdk-python.git\n $ cd threema-msgapi-sdk-python\n $ pip install -e .[dev]\n\nBefore creating a pull request, it is recommended to run the following\ncommands to check for code style violations (``flake8``), optimise\nimports (``isort``) and run the project's tests:\n\n.. code-block:: bash\n\n $ flake8 .\n $ isort .\n $ py.test\n\nYou should also run the type checker that might catch some additional bugs:\n\n.. code-block:: bash\n\n $ mypy setup.py tests examples threema\n\n.. _asyncio: https://docs.python.org/3/library/asyncio.html\n.. _venv: https://docs.python.org/3/library/venv.html\n.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/\n.. _libsodium: https://download.libsodium.org/doc/installation/index.html\n\nChangelog\n*********\n\n`8.0.0`_ (2024-08-21)\n---------------------\n\n- Add support for Python 3.10/3.11/3.12\n- Drop support for Python versions below 3.8\n- Bump dependencies\n- Add `caption` to file message and to the CLI\n- Add an optional parameter to the CLI for `send-simple` and `send-e2e` to allow\n passing the text as an argument instead from stdin.\n- Make the random padding spec compliant\n- Add an optional environment variable `GATEWAY_API_URL` to override the Gateway\n API Endpoint URL\n\n`7.0.1`_ (2023-02-21)\n---------------------\n\n- Fix parsing of unknown reception capabilities\n- Add new `ReceptionCapability` items\n- Remove `ReceptionCapabilitiesError` (breaking)\n\n`6.0.0`_ (2022-06-13)\n---------------------\n\nGeneral:\n\n- Add support for Python 3.10\n- Drop support for Python versions below 3.7\n- Major dependencies bump to increase compatibility with other packages\n- Updated all tests to work with the newest dependencies\n- Changed CLI syntax: All commands are now `dash-case` instead of `snake_case`,\n e.g. the `send_e2e` command is now called `send-e2e`.\n\n\n`5.0.0`_ (2021-05-17)\n---------------------\n\n- Add custom session and session arguments to `Connection` (#55, #56)\n- Remove the `fingerprint` and `verify_fingerprint` arguments, see #55 for a\n detailed explanation and how to achieve pinning\n\n`4.0.0`_ (2021-01-23)\n---------------------\n\nGeneral:\n\n- Drop support for Python versions below 3.6.1.\n- Remove `ReceiptType.user_ack` after deprecation. Use\n `ReceiptType.user_acknowledge` instead.\n- Simplify `util.aio_run`. It does not allow for passing a specific event loop\n or closing the event loop on completion any longer.\n- Rename `util.aio_run_proxy_decorator` to `aio_run_proxy`. It now always\n creates the class instance within a running event loop.\n\nClient:\n\n- In async mode, creation of the `Connection` instance must now be done within\n an `async` function.\n- If you have used a `with` context manager block in async mode before, you\n must now do this within an `async with` asynchronous context manager. No\n change is required in blocking mode.\n- `Connection.close` is now an async function.\n\nServer:\n\n- The callback server has been refactored and the `AbstractCallback` class has\n been removed for more flexibility and control of the underlying\n `aiohttp <https://docs.aiohttp.org>`_ server. Take a look at\n `examples/callback.py` on how to use it.\n- The callback server CLI has been removed because it was redundant. The\n example provides the same functionality.\n\n`3.1.0`_ (2020-04-21)\n---------------------\n\n- Add video message\n- Fix slightly off calculation of image byte length\n\n`3.0.6`_ (2017-09-22)\n---------------------\n\n- Migrate to aiohttp2\n\n`3.0.5`_ (2017-07-25)\n---------------------\n\n- Fix to handle new `libnacl <https://github.com/saltstack/libnacl/pull/91>`_\n exceptions.\n\n`3.0.4`_ (2017-05-23)\n---------------------\n\n- Fix CLI\n\n`3.0.2`_ (2017-05-12)\n---------------------\n\n- Initial publication on PyPI\n\n.. _8.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v7.0.1...v8.0.0\n.. _7.0.1: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v6.0.0...v7.0.1\n.. _6.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v5.0.0...v6.0.0\n.. _5.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v4.0.0...v5.0.0\n.. _4.0.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.1.0...v4.0.0\n.. _3.1.0: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.6...v3.1.0\n.. _3.0.6: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.5...v3.0.6\n.. _3.0.5: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.4...v3.0.5\n.. _3.0.4: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/v3.0.2...v3.0.4\n.. _3.0.2: https://github.com/threema-ch/threema-msgapi-sdk-python/compare/e982c74cbe564c76cc58322d3154916ee7f6863b...v3.0.2\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "An API for the Threema gateway service to send and receive messages including text, images, files and delivery reports.",
"version": "8.0.0",
"project_urls": {
"Homepage": "https://gateway.threema.ch/"
},
"split_keywords": [
"threema",
"gateway",
"service",
"sdk",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "050b86ede946c75ae7040fa1e3f4c86f304f4c091f12896d97ea0fe3de498663",
"md5": "b9c24a502e046318b5954193173d045b",
"sha256": "31459eb3bb7f6434e90d4d06e00bd007a84e27200a1176b4b0f27e6d8a1a0db2"
},
"downloads": -1,
"filename": "threema.gateway-8.0.0-py38.py39.py310.py311.py312-none-any.whl",
"has_sig": false,
"md5_digest": "b9c24a502e046318b5954193173d045b",
"packagetype": "bdist_wheel",
"python_version": "py38.py39.py310.py311.py312",
"requires_python": null,
"size": 31837,
"upload_time": "2024-08-21T19:36:36",
"upload_time_iso_8601": "2024-08-21T19:36:36.597759Z",
"url": "https://files.pythonhosted.org/packages/05/0b/86ede946c75ae7040fa1e3f4c86f304f4c091f12896d97ea0fe3de498663/threema.gateway-8.0.0-py38.py39.py310.py311.py312-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7ded3566a018210cebc1676755eb039367ca3298cd57a93adcd3491251b81f54",
"md5": "5fa8dd71d64d4e8ce4c086edc5fb2f76",
"sha256": "9a9e0852531752208dd3508a8063b4400b1f451eebceb82387ad23be422b238a"
},
"downloads": -1,
"filename": "threema_gateway-8.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5fa8dd71d64d4e8ce4c086edc5fb2f76",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 438871,
"upload_time": "2024-08-21T19:36:38",
"upload_time_iso_8601": "2024-08-21T19:36:38.955478Z",
"url": "https://files.pythonhosted.org/packages/7d/ed/3566a018210cebc1676755eb039367ca3298cd57a93adcd3491251b81f54/threema_gateway-8.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-21 19:36:38",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "threema.gateway"
}
JSON