././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1536692852.033692
jeepney-0.7.1/.gitignore 0000644 0000000 0000000 00000000061 00000000000 012032 0 ustar 00 __pycache__/
/dist/
/docs/_build/
.pytest_cache/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/.gitlab-ci.yml 0000644 0000000 0000000 00000001017 00000000000 012500 0 ustar 00 before_script:
- pip install '.[test]'
test_job_py39:
image: python:3.9
script:
- pytest
stage: test
test_job_py38:
image: python:3.8
script:
- pytest
stage: test
test_job_py37:
image: python:3.7
script:
- pytest
stage: test
test_job_py36:
image: python:3.6
script:
- pytest
stage: test
test_job_integration:
image: fedora:32
before_script:
- dnf install -y dbus-daemon python3-pip
- pip install '.[test,trio]'
script:
- dbus-run-session -- pytest
stage: test
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1488126885.792407
jeepney-0.7.1/LICENSE 0000644 0000000 0000000 00000002071 00000000000 011052 0 ustar 00 The MIT License (MIT)
Copyright (c) 2017 Thomas Kluyver
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/README.rst 0000644 0000000 0000000 00000000561 00000000000 011536 0 ustar 00 Jeepney is a pure Python implementation of D-Bus messaging. It has an `I/O-free
`__ core, and integration modules for different
event loops.
D-Bus is an inter-process communication system, mainly used in Linux.
To install Jeepney::
pip install jeepney
`Jeepney docs on Readthedocs `__
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1496064397.979681
jeepney-0.7.1/docs/Makefile 0000644 0000000 0000000 00000016672 00000000000 012451 0 ustar 00 # Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help
help:
@echo "Please use \`make ' where is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " epub3 to make an epub3"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
@echo " dummy to check syntax errors of document sources"
.PHONY: clean
clean:
rm -rf $(BUILDDIR)/*
.PHONY: html
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: dirhtml
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
.PHONY: json
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Jeepney.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Jeepney.qhc"
.PHONY: applehelp
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
.PHONY: devhelp
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Jeepney"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Jeepney"
@echo "# devhelp"
.PHONY: epub
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: epub3
epub3:
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
@echo
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
.PHONY: latex
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: latexpdfja
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
.PHONY: info
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: linkcheck
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: doctest
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: coverage
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
.PHONY: xml
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: pseudoxml
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
.PHONY: dummy
dummy:
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
@echo
@echo "Build finished. Dummy builder generates no files."
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/asyncio.rst 0000644 0000000 0000000 00000001150 00000000000 013742 0 ustar 00 Asyncio integration
===================
This supports D-Bus in applications built with
`asyncio `_.
See :ref:`connections_and_routers` for more about the two interfaces.
.. module:: jeepney.io.asyncio
.. autofunction:: open_dbus_router
.. autoclass:: DBusRouter
.. automethod:: send
.. automethod:: send_and_get_reply
.. automethod:: filter
.. autoclass:: Proxy
.. seealso:: :ref:`msggen_proxies`
.. autofunction:: open_dbus_connection
.. autoclass:: DBusConnection
.. automethod:: send
.. automethod:: receive
.. automethod:: close
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/auth.rst 0000644 0000000 0000000 00000003211 00000000000 013236 0 ustar 00 Authentication
==============
.. note::
If you use any of Jeepney's I/O integrations, authentication is built
in. You only need these functions if you're working outside that.
If you are setting up a socket for D-Bus, you will need to do `SASL
`_
authentication before starting to send and receive D-Bus messages.
This text based protocol is completely different to D-Bus itself.
Only a small fraction of SASL is implemented here, primarily what Jeepney's
integration layer uses. If you're doing something different, you may need to
implement other messages yourself.
.. module:: jeepney.auth
.. autofunction:: make_auth_external
.. autofunction:: make_auth_anonymous
.. data:: BEGIN
Send this just before switching to the D-Bus protocol.
.. autoclass:: Authenticator
.. versionchanged:: 0.7
This class was renamed from ``SASLParser`` and substantially changed.
.. attribute:: authenticated
Initially False, changes to True when authentication has succeeded.
.. attribute:: error
``None``, or the raw bytes of an error message if authentication failed.
.. automethod:: data_to_send
.. automethod:: feed
.. autoexception:: AuthenticationError
.. autoexception:: FDNegotiationError
Typical flow
------------
1. Send the data from :meth:`Authenticator.data_to_send` (or
``for req_data in authenticator``).
2. Receive data from the server, pass to :meth:`Authenticator.feed`.
3. Repeat 1 & 2 until :attr:`Authenticator.authenticated` is True, or the for
loop exits.
4. Send :data:`BEGIN`.
5. Start sending & receiving D-Bus messages.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/blocking.rst 0000644 0000000 0000000 00000001346 00000000000 014074 0 ustar 00 Blocking I/O
============
This is a good option for simple scripts, where you don't need to do anything
else while waiting for a D-Bus reply. If you will use D-Bus for multiple
threads, or you want a nicer way to wait for signals, see :doc:`threading`.
.. module:: jeepney.io.blocking
.. autofunction:: open_dbus_connection
.. autoclass:: DBusConnection
.. automethod:: send
.. automethod:: receive
.. automethod:: send_and_get_reply
.. automethod:: recv_messages
.. automethod:: filter
.. automethod:: recv_until_filtered
.. automethod:: close
Using ``with open_dbus_connection()`` will also close the connection on
exiting the block.
.. autoclass:: Proxy
.. seealso:: :ref:`msggen_proxies`
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/common_msgs.rst 0000644 0000000 0000000 00000000671 00000000000 014625 0 ustar 00 Common messages
===============
.. currentmodule:: jeepney
These classes are *message generators*. Wrap them in a :ref:`Proxy
` class to actually send the messages as well.
.. autoclass:: Properties
:members:
.. autoclass:: Introspectable
:members:
.. autoclass:: DBus
:members:
:undoc-members:
There is a ready-made instance of this at ``jeepney.message_bus``.
.. autoclass:: Monitoring
:members:
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/core.rst 0000644 0000000 0000000 00000007553 00000000000 013242 0 ustar 00 Core API
========
.. module:: jeepney
Message constructors
--------------------
.. autofunction:: new_method_call
.. autofunction:: new_method_return
.. autofunction:: new_error
.. autofunction:: new_signal
.. autoclass:: DBusAddress
.. autoclass:: MessageGenerator
.. seealso:: :doc:`/bindgen`
Parsing
-------
.. autoclass:: Parser
.. automethod:: add_data
.. automethod:: get_next_message
Message objects
---------------
.. autoclass:: Message
.. attribute:: header
A :class:`Header` object
.. attribute:: body
A tuple of the data in this message. The number and types of the elements
depend on the message's signature:
=========== ========== ===========
D-Bus type D-Bus code Python type
=========== ========== ===========
BYTE ``y`` int
BOOLEAN ``b`` bool
INT16 ``n`` int
UINT16 ``q`` int
INT32 ``i`` int
UINT32 ``u`` int
INT64 ``x`` int
UINT64 ``t`` int
DOUBLE ``d`` float
STRING ``s`` str
OBJECT_PATH ``o`` str
SIGNATURE ``g`` str
ARRAY ``a`` list
STRUCT ``()`` tuple
VARIANT ``v`` 2-tuple ``(signature, value)``
DICT_ENTRY ``{}`` dict (for array of dict entries)
UNIX_FD ``h`` See :ref:`send_recv_fds`
=========== ========== ===========
.. automethod:: serialise
.. autoclass:: Header
.. attribute:: endianness
:class:`Endianness` object, affecting message serialisation.
.. attribute:: message_type
:class:`MessageType` object.
.. attribute:: flags
:class:`MessageFlag` object.
.. attribute:: protocol_version
Currently always 1.
.. attribute:: body_length
The length of the raw message body in bytes.
.. attribute:: serial
Sender's serial number for this message. This is not necessarily set
for outgoing messages - see :meth:`Message.serialise`.
.. attribute:: fields
Mapping of :class:`HeaderFields` values to the relevant Python objects.
Exceptions
----------
.. autoexception:: SizeLimitError
.. autoexception:: DBusErrorResponse
.. attribute:: name
The error name from the remote end.
.. attribute:: body
Any data fields contained in the error message.
Enums & Flags
-------------
.. class:: Endianness
.. autoattribute:: little
.. autoattribute:: big
.. class:: HeaderFields
.. autoattribute:: path
.. autoattribute:: interface
.. autoattribute:: member
.. autoattribute:: error_name
.. autoattribute:: reply_serial
.. autoattribute:: destination
.. autoattribute:: sender
.. autoattribute:: signature
.. autoattribute:: unix_fds
.. class:: MessageFlag
.. autoattribute:: no_reply_expected
On a method call message, indicates that a reply should not be sent.
.. autoattribute:: no_auto_start
D-Bus includes a mechanism to start a service on demand to handle
messages. If this flag is set, it will avoid that, only handling the
message if the target is already running.
.. autoattribute:: allow_interactive_authorization
Signals that the recipient may prompt the user for elevated privileges
to handle the request. The D-Bus specification has more details.
.. class:: MessageType
.. autoattribute:: method_call
.. autoattribute:: method_return
.. autoattribute:: error
.. autoattribute:: signal
Matching messages
-----------------
.. autoclass:: MatchRule
MatchRule objects are used both for filtering messages internally, and for
setting up subscriptions in the message bus.
.. automethod:: add_arg_condition
.. automethod:: matches
.. automethod:: serialise
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/fds.rst 0000644 0000000 0000000 00000001550 00000000000 013055 0 ustar 00 File descriptor support
=======================
.. currentmodule:: jeepney
.. autoclass:: FileDescriptor
.. automethod:: to_file
.. note::
If the descriptor does not refer to a regular file, or it doesn't have
the right access mode, you may get strange behaviour or errors while
using it.
You can use :func:`os.stat` and the :mod:`stat` module to check the
type of object the descriptor refers to, and :func:`fcntl.fcntl`
to check the access mode, e.g.::
stat.S_ISREG(os.stat(fd.fileno()).st_mode) # Regular file?
status_flags = fcntl.fcntl(fd, fcntl.F_GETFL)
(status_flags & os.O_ACCMODE) == os.O_RDONLY # Read-only?
.. automethod:: to_socket
.. automethod:: to_raw_fd
.. automethod:: fileno
.. automethod:: close
.. autoexception:: NoFDError
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/index.rst 0000644 0000000 0000000 00000000616 00000000000 013412 0 ustar 00 API reference
=============
.. toctree::
:maxdepth: 2
core
common_msgs
auth
fds
.. toctree::
:maxdepth: 2
:caption: I/O integrations
blocking
threading
trio
asyncio
io_exceptions
There is also a deprecated ``jeepney.io.tornado`` integration. Recent versions
of Tornado are built on asyncio, so you can use the asyncio integration with
Tornado applications.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1810296
jeepney-0.7.1/docs/api/io_exceptions.rst 0000644 0000000 0000000 00000000136 00000000000 015150 0 ustar 00 I/O Exceptions
==============
.. currentmodule:: jeepney.io
.. autoexception:: RouterClosed
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1820295
jeepney-0.7.1/docs/api/threading.rst 0000644 0000000 0000000 00000001350 00000000000 014244 0 ustar 00 Blocking I/O with threads
=========================
This allows using a D-Bus connection from multiple threads.
The router also launches a separate thread to receive incoming messages.
See :ref:`connections_and_routers` for more about the two interfaces.
.. module:: jeepney.io.threading
.. autofunction:: open_dbus_router
.. autoclass:: DBusRouter
.. automethod:: send
.. automethod:: send_and_get_reply
.. automethod:: filter
.. automethod:: close
Leaving the ``with`` block will also close the router.
.. autoclass:: Proxy
.. seealso:: :ref:`msggen_proxies`
.. autofunction:: open_dbus_connection
.. autoclass:: DBusConnection
.. automethod:: send
.. automethod:: receive
.. automethod:: close
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1820295
jeepney-0.7.1/docs/api/trio.rst 0000644 0000000 0000000 00000001317 00000000000 013257 0 ustar 00 Trio integration
================
This supports D-Bus in applications built with
`Trio `_.
See :ref:`connections_and_routers` for more about the two interfaces.
.. module:: jeepney.io.trio
.. autofunction:: open_dbus_router
.. autoclass:: DBusRouter
.. automethod:: send
.. automethod:: send_and_get_reply
.. automethod:: filter
.. automethod:: aclose
Leaving the ``async with`` block will also close the router.
.. autoclass:: Proxy
.. seealso:: :ref:`msggen_proxies`
.. autofunction:: open_dbus_connection
.. autoclass:: DBusConnection
.. automethod:: send
.. automethod:: receive
.. automethod:: router
.. automethod:: aclose
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1820295
jeepney-0.7.1/docs/bindgen.rst 0000644 0000000 0000000 00000001536 00000000000 013142 0 ustar 00 Generating D-Bus wrappers
=========================
D-Bus includes a mechanism to introspect remote objects and discover the methods
they define. Jeepney can use this to generate classes defining the messages to
send. Use it like this::
python3 -m jeepney.bindgen --name org.freedesktop.Notifications \
--path /org/freedesktop/Notifications
This command will produce the class in the example under :ref:`msggen_proxies`.
You specify *name*—which D-Bus service you're talking to—and *path*—an
object in that service. Jeepney will generate a wrapper for each interface that
object has, except for some standard ones like the introspection interface
itself.
You are welcome to edit the generated code, e.g. to add docstrings or give
parameters meaningful names. Names like ``arg_1`` are created when
introspection doesn't provide a name.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1850295
jeepney-0.7.1/docs/conf.py 0000644 0000000 0000000 00000023516 00000000000 012303 0 ustar 00 #!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Jeepney documentation build configuration file, created by
# sphinx-quickstart on Mon May 29 14:26:37 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.intersphinx',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'Jeepney'
copyright = '2017, Thomas Kluyver'
author = 'Thomas Kluyver'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
import jeepney
version = jeepney.__version__
# The full version, including alpha/beta/rc tags.
release = version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
}
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents.
# " v documentation" by default.
#
# html_title = 'Jeepney v0.3'
# A shorter title for the navigation bar. Default is the same as html_title.
#
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []
# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}
# If false, no module index is generated.
#
# html_domain_indices = True
# If false, no index is generated.
#
# html_use_index = True
# If true, the index is split into individual pages for each letter.
#
# html_split_index = False
# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'Jeepneydoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'Jeepney.tex', 'Jeepney Documentation',
'Thomas Kluyver', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#
# latex_use_parts = False
# If true, show page references after internal links.
#
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
#
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
#
# latex_appendices = []
# It false, will not define \strong, \code, itleref, \crossref ... but only
# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
# packages.
#
# latex_keep_old_macro_names = True
# If false, no module index is generated.
#
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'jeepney', 'Jeepney Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'Jeepney', 'Jeepney Documentation',
author, 'Jeepney', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []
# If false, no module index is generated.
#
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1850295
jeepney-0.7.1/docs/design.rst 0000644 0000000 0000000 00000006551 00000000000 013007 0 ustar 00 Design & Limitations
====================
There are two parts to Jeepney:
The **core** is all about creating D-Bus messages, serialising them to bytes,
and deserialising bytes into :class:`.Message` objects.
It aims to be a complete & reliable implementation of the D-Bus wire protocol.
It follows the idea of `"Sans-I/O" `_,
implementing the D-Bus protocol independent of any means of sending or receiving
the data.
The second part is **I/O integration**. This supports the typical use case for
D-Bus - connecting to a message bus on a Unix socket - with various I/O
frameworks. There is one integration module for each framework, and they provide
similar interfaces (:ref:`connections_and_routers`), but differ as much as
necessary to fit in with the different frameworks - e.g. the Trio integration
uses channels where the asyncio integration uses queues.
Jeepney also allows for a similar split in code using it. If you want to wrap
the desktop notifications service, for instance, you can write (or generate) a
:ref:`message generator ` class for it.
The same message generator class can then be wrapped in a *proxy* for any of
Jeepney's I/O integrations.
Non-goals
---------
Jeepney does not (currently) aim for:
- Very high performance. Parsing binary messages in pure Python code is not
the fastest way to do it, but for many use cases of D-Bus it's more than fast
enough.
- Supporting all possible D-Bus transports. The I/O integration layer only works
with Unix sockets, the most common way to use D-Bus. If you need to use
another transport, you can still use :meth:`.Message.serialise` and
:class:`.Parser`, and deal with sending & receiving data yourself.
- Supporting all authentication options. The :doc:`auth module `
only provides what the I/O integration layer uses.
- High-level server APIs. Jeepney's API for D-Bus servers is on a low-level,
sending and receiving messages, not registering handler methods. See
`dbus-objects `_ for a server API
built on top of Jeepney.
- 'Magic' introspection. Some D-Bus libraries use introspection at runtime to
discover available methods, but Jeepney does not. Instead, it uses
introspection during development to write message generators (:doc:`bindgen`).
Alternatives
------------
* GTK applications can use `Gio.DBusConnection
`_
or a higher-level wrapper like `dasbus `_
or `pydbus `_.
There are also GObject wrappers for specific D-Bus services, e.g.
`secret storage `__ and
`desktop notifications `__.
* PyQt applications can use the `Qt D-Bus module
`_, although as of 2020, this is
`not exposed by PySide `__.
* `dbus-python `_ is a Python
binding to the reference D-Bus implementation in C. It is very complete and
well tested, but may be trickier to install and to integrate with event loops
and async frameworks.
.. seealso::
`D-Bus Python bindings on the Freedesktop wiki
`_
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1850295
jeepney-0.7.1/docs/index.rst 0000644 0000000 0000000 00000002404 00000000000 012636 0 ustar 00 Jeepney |version|
=================
Jeepney is a pure Python interface to D-Bus, a protocol for interprocess
communication on desktop Linux (mostly).
The core of Jeepney is `I/O free `__, and the
``jeepney.io`` package contains bindings for different event loops to
handle I/O. Jeepney tries to be *non-magical*, so you may have to write a bit
more code than with other interfaces such as `dbus-python `_
or `pydbus `_.
Jeepney doesn't rely on libdbus or other compiled libraries, so it's easy
to install with Python tools like ``pip``::
pip install jeepney
For most use cases, the D-Bus daemon needs to be running on your computer;
this is a standard part of most modern Linux desktops.
Contents:
.. toctree::
:maxdepth: 2
integrate
messages
bindgen
api/index
design
release-notes
.. seealso::
`D-Feet `__
App for exploring available D-Bus services on your machine.
`D-Bus Specification `__
Technical details about the D-Bus protocol.
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1850295
jeepney-0.7.1/docs/integrate.rst 0000644 0000000 0000000 00000010412 00000000000 013507 0 ustar 00 Connecting to DBus and sending messages
=======================================
Jeepney can be used with several different frameworks:
- Blocking I/O
- Multi-threading with the `threading `_ module
- `Trio `_
- `asyncio `_
- `Tornado `_ (Deprecated as the asyncio
integration should work with Tornado)
For each of these, there is a module in ``jeepney.io`` providing the
integration layer.
Here's an example of sending a desktop notification, using blocking I/O:
.. literalinclude:: /../examples/blocking_notify.py
And here is the same thing using asyncio:
.. literalinclude:: /../examples/aio_notify_noproxy.py
See the `examples folder `_
in Jeepney's source repository for more examples.
.. _connections_and_routers:
Connections and Routers
-----------------------
Each integration (except blocking I/O) can create *connections* and *routers*.
**Routers** are useful for calling methods in other processes.
Routers let you send a request and wait for a reply, using a
:ref:`proxy ` or with ``router.send_and_get_reply()``.
You can also filter incoming messages into queues, e.g. to wait for a specific
signal. But if messages arrive faster than they are processed, these queues fill
up, and messages may be dropped.
**Connections** are simpler: they let you send and receive messages, but
``conn.receive()`` will give you the next message read, whatever that is.
You'd use this to write a server which responds to incoming messages.
A connection will never discard an incoming message.
.. note::
For blocking, single-threaded I/O, the connection doubles as a router.
Incoming messages while you're waiting for a reply will be filtered,
and you can also filter the next message by calling ``conn.recv_messages()``.
Routers for the other integrations receive messages in a background task.
.. _msggen_proxies:
Message generators and proxies
------------------------------
If you're calling a number of different methods, you can make a *message
generator* class containing their definitions. Jeepney includes a tool to
generate these classes automatically—see :doc:`bindgen`.
Message generators define how to construct messages. *Proxies* are wrappers
around message generators which send a message and get the reply back.
Let's rewrite the example above to use a message generator and a proxy:
.. literalinclude:: /../examples/aio_notify.py
This is more code for the simple use case here, but in a larger application
collecting the message definitions together like this could make it clearer.
.. _send_recv_fds:
Sending & receiving file descriptors
------------------------------------
.. versionadded:: 0.7
D-Bus allows sending file descriptors - references to open files, sockets, etc.
To use this, use the blocking, multi-threading or Trio integration and enable it
(``enable_fds=True``) when connecting to D-Bus. If you enable FD support but the
message bus can't or won't support it, :exc:`.FDNegotiationError` will be raised.
To send a file descriptor, pass any object with a ``.fileno()`` method, such as
an open file or socket, or a suitable integer. The file descriptor must not be
closed before the message is sent.
A received file descriptor will be returned as a :class:`.FileDescriptor` object
to help avoid leaking FDs. This can easily be converted to
a file object (:meth:`~.FileDescriptor.to_file`),
a socket (:meth:`~.FileDescriptor.to_socket`)
or a plain integer (:meth:`~.FileDescriptor.to_raw_fd`).
.. code-block:: python
# Send a file descriptor for a temp file (normally not visible in any folder)
with TemporaryFile() as tf:
msg = new_method_call(server, 'write_data', 'h', (tf,))
await router.send_and_get_reply(msg)
# Receive a file descriptor, use it as a writable file
msg = await conn.receive()
fd, = msg.body
with fd.to_file('w') as f:
f.write(f'Timestamp: {datetime.now()}')
The snippets above are based on the Trio integration. See the
`examples directory `__
in the Jeepney repository for complete, working examples.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1860294
jeepney-0.7.1/docs/messages.rst 0000644 0000000 0000000 00000004570 00000000000 013344 0 ustar 00 Making and parsing messages
===========================
The core of Jeepney is code to build, serialise and deserialise D-Bus messages.
.. currentmodule:: jeepney
Making messages
---------------
D-Bus has four message types. Three, *method call*, *method return* and *error*,
are used in a request-reply pattern. The fourth, *signal*, is a broadcast
message with no reply.
- *Method call* messages are most conveniently made with a message generator
class, which can be :doc:`autogenerated `. One layer down from this
is :func:`new_method_call`, which takes a :class:`DBusAddress` object.
- *Method return* and *error* messages are made with
:func:`new_method_return` and :func:`new_error`, passing the method call
message which they are replying to.
- *signal* messages are made with :func:`new_signal`, which takes a
:class:`DBusAddress` representing the sender.
All of these return a :class:`Message` object. :meth:`Message.serialise`
converts it to bytes, but none of these core methods ever send a message.
See the :doc:`integration layer ` for that.
Signatures
~~~~~~~~~~
D-Bus is strongly typed, and every message has a *signature* describing the body
data. These are strings using characters such as ``i`` for a signed 32-bit
integer. See the `DBus specification `_
for the full list.
Jeepney does not try to guess or discover the signature when you build a
message: your code must explicitly specify a signature for every message.
However, Jeepney can help you write this code: see :doc:`bindgen`.
D-Bus types are converted to and from native Python objects as follows:
* All the D-Bus integer types are represented as Python :class:`int`,
including *BYTE* when it's not in an array.
* *BOOLEAN* is :class:`bool`.
* *DOUBLE* is :class:`float`.
* *STRING*, *OBJECT_PATH* and *SIGNATURE* are all :class:`str`.
* *ARRAY* is :class:`list`, except that an array of *BYTE* is a
:class:`bytes` object, and an array of *DICT_ENTRY* is a :class:`dict`.
* *STRUCT* is :class:`tuple`.
* *VARIANT* is a 2-tuple ``(signature, data)``. E.g. to put a string into
a variant field, you would pass the data ``("s", "my string")``.
* *UNIX_FD* are converted from objects with a ``.fileno()`` method
or plain integers, and converted to :class:`.FileDescriptor` objects. See
:ref:`send_recv_fds` for more details.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1627495890.1620867
jeepney-0.7.1/docs/release-notes.rst 0000644 0000000 0000000 00000006524 00000000000 014304 0 ustar 00 Release notes
=============
0.7.1
-----
* Add ``async with`` support to :class:`~.asyncio.DBusConnection` in the
asyncio integration.
* Fix calling :meth:`~.asyncio.DBusConnection.receive` immediately after opening
a connection in the asyncio integration.
Thanks to Aleksandr Mezin for these changes.
0.7
---
* Support for :ref:`sending and receiving file descriptors `.
This is available with the blocking, threading and trio integration layers.
* Deprecated older integration APIs, in favour of new APIs introduced in 0.5.
* Fixed passing a deque in to :meth:`~.blocking.DBusConnection.filter` in the
blocking integration API.
0.6
---
* New method :meth:`~.blocking.DBusConnection.recv_until_filtered` in the
blocking I/O integration to receive messages until one is filtered into a
queue.
* More efficient buffering of received data waiting to be parsed into D-Bus
messages.
0.5
---
* New common scheme for I/O integration - see :ref:`connections_and_routers`.
* This is designed for tasks to wait for messages and then act on them,
rather than triggering callbacks. This is based on ideas from 'structured
concurrency', which also informs the design of Trio. See `this blog post
by Nathaniel Smith `_
for more background.
* There are new integrations for :doc:`Trio ` and :doc:`threading
`.
* The old integration interfaces should still work for now, but they will be
deprecated and eventually removed.
* :meth:`.Message.serialise` accepts a serial number, to serialise outgoing
messages without modifying the message object.
* Improved documentation, including :doc:`API docs `.
0.4.3
-----
* The blocking integration now throws ``ConnectionResetError`` on all systems
when the connection was closed from the other end. It would previously hang
on some systems.
0.4.2
-----
* The blocking ``DBusConnection`` integration class now has a ``.close()``
method, and can be used as a context manager::
from jeepney.integrate.blocking import connect_and_authenticate
with connect_and_authenticate() as connection:
...
0.4.1
-----
* Avoid using :class:`asyncio.Future` for the blocking integration.
* Set the 'destination' field on method return and error messages to the
'sender' from the parent message.
Thanks to Oscar Caballero and Thomas Grainger for contributing to this release.
0.4
---
* Authentication failures now raise a new :exc:`AuthenticationError`
subclass of :exc:`ValueError`, so that they can be caught specifically.
* Fixed logic error when authentication is rejected.
* Use *effective* user ID for authentication instead of *real* user ID.
In typical use cases these are the same, but where they differ, effective
uid seems to be the relevant one.
* The 64 MiB size limit for an array is now checked when serialising it.
* New function :func:`jeepney.auth.make_auth_anonymous` to prepare an anonymous
authentication message. This is not used by the wrappers in Jeepney at the
moment, but may be useful for third party code in some situations.
* New examples for subscribing to D-Bus signals, with blocking I/O and with
asyncio.
* Various improvements to documentation.
Thanks to Jane Soko and Gitlab user xiretza for contributing to this release.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1860294
jeepney-0.7.1/docs/requirements.txt 0000644 0000000 0000000 00000000015 00000000000 014255 0 ustar 00 trio
outcome
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1860294
jeepney-0.7.1/examples/aio_hello.py 0000644 0000000 0000000 00000000320 00000000000 014163 0 ustar 00 import asyncio
from jeepney.io.asyncio import open_dbus_connection
async def hello():
conn = await open_dbus_connection(bus='SESSION')
print('My ID is:', conn.unique_name)
asyncio.run(hello())
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1860294
jeepney-0.7.1/examples/aio_notify.py 0000644 0000000 0000000 00000003546 00000000000 014405 0 ustar 00 """Send a desktop notification
See also aio_notify_noproxy.py, which does the same with lower-level APIs
"""
import asyncio
from jeepney import MessageGenerator, new_method_call
from jeepney.io.asyncio import open_dbus_router, Proxy
# ---- Message generator, created by jeepney.bindgen ----
class Notifications(MessageGenerator):
interface = 'org.freedesktop.Notifications'
def __init__(self, object_path='/org/freedesktop/Notifications',
bus_name='org.freedesktop.Notifications'):
super().__init__(object_path=object_path, bus_name=bus_name)
def Notify(self, arg_0, arg_1, arg_2, arg_3, arg_4, arg_5, arg_6, arg_7):
return new_method_call(self, 'Notify', 'susssasa{sv}i',
(arg_0, arg_1, arg_2, arg_3, arg_4, arg_5, arg_6, arg_7))
def CloseNotification(self, arg_0):
return new_method_call(self, 'CloseNotification', 'u',
(arg_0,))
def GetCapabilities(self):
return new_method_call(self, 'GetCapabilities')
def GetServerInformation(self):
return new_method_call(self, 'GetServerInformation')
# ---- End auto generated code ----
async def send_notification():
async with open_dbus_router() as router:
proxy = Proxy(Notifications(), router)
resp = await proxy.Notify('jeepney_test', # App name
0, # Not replacing any previous notification
'', # Icon
'Hello, world!', # Summary
'This is an example notification from Jeepney',
[], {}, # Actions, hints
-1, # expire_timeout (-1 = default)
)
print('Notification ID:', resp[0])
if __name__ == '__main__':
asyncio.run(send_notification())
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1870296
jeepney-0.7.1/examples/aio_notify_noproxy.py 0000644 0000000 0000000 00000002362 00000000000 016176 0 ustar 00 """Send a desktop notification
See also aio_notify.py, which does the same with the higher-level Proxy API.
"""
import asyncio
from jeepney import DBusAddress, new_method_call
from jeepney.io.asyncio import open_dbus_router
notifications = DBusAddress('/org/freedesktop/Notifications',
bus_name='org.freedesktop.Notifications',
interface='org.freedesktop.Notifications')
async def send_notification():
msg = new_method_call(notifications, 'Notify', 'susssasa{sv}i',
('jeepney_test', # App name
0, # Not replacing any previous notification
'', # Icon
'Hello, world!', # Summary
'This is an example notification from Jeepney',
[], {}, # Actions, hints
-1, # expire_timeout (-1 = default)
))
# Send the message and await the reply
async with open_dbus_router() as router:
reply = await router.send_and_get_reply(msg)
print('Notification ID:', reply.body[0])
loop = asyncio.get_event_loop()
loop.run_until_complete(send_notification())
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1870296
jeepney-0.7.1/examples/aio_secretstorage.py 0000644 0000000 0000000 00000002232 00000000000 015736 0 ustar 00 """Example accessing the SecretStorage DBus interface with asyncio APIs
https://freedesktop.org/wiki/Specifications/secret-storage-spec/secrets-api-0.1.html#ref-dbus-api
"""
import asyncio
from jeepney import new_method_call, DBusAddress, Properties
from jeepney.io.asyncio import open_dbus_router
secrets = DBusAddress('/org/freedesktop/secrets',
bus_name= 'org.freedesktop.secrets',
interface='org.freedesktop.Secret.Service')
login_keyring = DBusAddress('/org/freedesktop/secrets/collection/login',
bus_name= 'org.freedesktop.secrets',
interface='org.freedesktop.Secret.Collection')
search_msg = new_method_call(
login_keyring, 'SearchItems', 'a{ss}', ({'user': 'tk2e15',},)
)
async def query_secrets():
async with open_dbus_router() as router:
get_collections_msg = Properties(secrets).get('Collections')
resp = await router.send_and_get_reply(get_collections_msg)
print('Collections:', resp.body[0][1])
resp = await router.send_and_get_reply(search_msg)
print('Search res:', resp.body)
asyncio.run(query_secrets())
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930450.1253824
jeepney-0.7.1/examples/aio_subscribe.py 0000644 0000000 0000000 00000004163 00000000000 015052 0 ustar 00 """
This example simulates two clients interacting with the message bus, more or
less independently.
Client 1
Any app on the bus (here, called *service*). It asks the bus for sole
custody of its preferred name, a `well-known bus name`_ that it wants
others to recognize.
Client 2
An interested party (here, called *watcher*). It asks the bus to emit a
signal (send it an update) whenever *service*'s well-known bus name changes
hands. It uses Jeepney's ``router.filter()`` to get a message whenever this
happens.
.. _well-known bus name: https://dbus.freedesktop.org/doc
/dbus-specification.html#message-protocol-names
"""
import asyncio
from jeepney.io.asyncio import open_dbus_router, Proxy
from jeepney.bus_messages import message_bus, MatchRule
well_known_bus_name = "io.readthedocs.jeepney.aio_subscribe_example"
async def watcher(ready: asyncio.Event):
# Create a "signal-selection" match rule
match_rule = MatchRule(
type="signal",
sender=message_bus.bus_name,
interface=message_bus.interface,
member="NameOwnerChanged",
path=message_bus.object_path,
)
# Condition: arg number 0 must match the bus name (try changing either)
match_rule.add_arg_condition(0, well_known_bus_name)
async with open_dbus_router() as router:
await Proxy(message_bus, router).AddMatch(match_rule)
with router.filter(match_rule) as q:
print("[watcher] subscribed to NameOwnerChanged signal")
ready.set()
msg = await q.get()
print("[watcher] match hit:", msg.body)
async def main():
watcher_ready = asyncio.Event()
watcher_task = asyncio.create_task(watcher(watcher_ready))
await watcher_ready.wait()
async with open_dbus_router() as router:
print("[service] calling 'RequestName'")
resp = await Proxy(message_bus, router).RequestName(well_known_bus_name, 4)
print("[service] reply:", (None, "primary owner", "in queue",
"exists", "already owned")[resp[0]])
await watcher_task
if __name__ == "__main__":
asyncio.run(main())
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1870296
jeepney-0.7.1/examples/blocking_choose_file.py 0000644 0000000 0000000 00000002501 00000000000 016362 0 ustar 00 from jeepney import DBusAddress, new_method_call
from jeepney.bus_messages import message_bus, MatchRule
from jeepney.io.blocking import open_dbus_connection, Proxy
portal = DBusAddress(
object_path='/org/freedesktop/portal/desktop',
bus_name='org.freedesktop.portal.Desktop',
)
filechooser = portal.with_interface('org.freedesktop.portal.FileChooser')
conn = open_dbus_connection()
token = 'file_choice_1'
sender_name = conn.unique_name[1:].replace('.', '_')
handle = f"/org/freedesktop/portal/desktop/request/{sender_name}/{token}"
response_rule = MatchRule(
type='signal', interface='org.freedesktop.portal.Request', path=handle
)
Proxy(message_bus, conn).AddMatch(response_rule)
with conn.filter(response_rule) as responses:
# https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-method-org-freedesktop-portal-FileChooser.OpenFile
req = new_method_call(filechooser, 'OpenFile', 'ssa{sv}', (
# Parent window, title, options
'', 'Pick a file', {'handle_token': ('s', token)}
))
conn.send_and_get_reply(req)
# responses is a deque - process messages until one is filtered into it
response_msg = conn.recv_until_filtered(responses)
response, results = response_msg.body
if response == 0:
# print(results)
print("Chose file:", results['uris'][1][0])
conn.close()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1870296
jeepney-0.7.1/examples/blocking_notify.py 0000644 0000000 0000000 00000002137 00000000000 015420 0 ustar 00 from jeepney import DBusAddress, new_method_call
from jeepney.io.blocking import open_dbus_connection
notifications = DBusAddress('/org/freedesktop/Notifications',
bus_name='org.freedesktop.Notifications',
interface='org.freedesktop.Notifications')
connection = open_dbus_connection(bus='SESSION')
# Construct a new D-Bus message. new_method_call takes the address, the
# method name, the signature string, and a tuple of arguments.
msg = new_method_call(notifications, 'Notify', 'susssasa{sv}i',
('jeepney_test', # App name
0, # Not replacing any previous notification
'', # Icon
'Hello, world!', # Summary
'This is an example notification from Jeepney',
[], {}, # Actions, hints
-1, # expire_timeout (-1 = default)
))
# Send the message and wait for the reply
reply = connection.send_and_get_reply(msg)
print('Notification ID:', reply.body[0])
connection.close()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1870296
jeepney-0.7.1/examples/blocking_pick_colour.py 0000644 0000000 0000000 00000004372 00000000000 016424 0 ustar 00 """Pick a colour on your screen, show its details in the terminal
This probably only works on Gnome desktops, as it uses a Gnome D-Bus interface.
This is just an example, so broad support is less important than simplicity.
"""
from jeepney.io.blocking import open_dbus_connection, Proxy
from jeepney.wrappers import MessageGenerator, new_method_call
# This class was auto-generated with:
# python3 -m jeepney.bindgen --name org.gnome.Shell.Screenshot --path /org/gnome/Shell/Screenshot
class Screenshot(MessageGenerator):
interface = 'org.gnome.Shell.Screenshot'
def __init__(self, object_path='/org/gnome/Shell/Screenshot',
bus_name='org.gnome.Shell.Screenshot'):
super().__init__(object_path=object_path, bus_name=bus_name)
def Screenshot(self, include_cursor, flash, filename):
return new_method_call(self, 'Screenshot', 'bbs',
(include_cursor, flash, filename))
def ScreenshotWindow(self, include_frame, include_cursor, flash, filename):
return new_method_call(self, 'ScreenshotWindow', 'bbbs',
(include_frame, include_cursor, flash, filename))
def ScreenshotArea(self, x, y, width, height, flash, filename):
return new_method_call(self, 'ScreenshotArea', 'iiiibs',
(x, y, width, height, flash, filename))
def PickColor(self):
return new_method_call(self, 'PickColor')
def FlashArea(self, x, y, width, height):
return new_method_call(self, 'FlashArea', 'iiii',
(x, y, width, height))
def SelectArea(self):
return new_method_call(self, 'SelectArea')
with open_dbus_connection() as conn:
screenshot = Proxy(Screenshot(), conn)
res_dict, = screenshot.PickColor()
# We get RGB as floats (0-1), and convert to integers (0-255)
rf, gf, bf = res_dict['color'][1]
ri, gi, bi = round(rf * 255), round(gf * 255), round(bf * 255)
print(f"RGB (0-1) : ({rf:.5f}, {gf:.5f}, {bf:.5f})")
print(f"RGB (0-255): {ri, gi, bi}")
print(f"Hex code : #{ri:02X}{gi:02X}{bi:02X}")
print(f"Preview : \x1b[48;2;{ri};{gi};{bi}m \x1b[0m")
# The line above assumes our terminal supports 24-bit colour:
# https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1870296
jeepney-0.7.1/examples/blocking_recv_fd.py 0000644 0000000 0000000 00000003012 00000000000 015511 0 ustar 00 """Demonstrate receiving a file descriptor
Start this, and then run one of the _send_fd.py scripts to send requests.
"""
from datetime import datetime
from jeepney import MessageType, HeaderFields, new_method_return, new_error
from jeepney.bus_messages import message_bus
from jeepney.io.blocking import open_dbus_connection
SERVER_NAME = "io.gitlab.takluyver.jeepney.examples.FDWriter"
with open_dbus_connection(enable_fds=True) as connection:
print("My unique name is:", connection.unique_name)
# Request an additional name on the message bus
rep = connection.send_and_get_reply(message_bus.RequestName(SERVER_NAME))
if rep.body[0] == 1: # DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
print("Got name", SERVER_NAME)
while True:
msg = connection.receive()
if msg.header.message_type != MessageType.method_call:
print("Received non-method-call message:", msg)
method = msg.header.fields[HeaderFields.member]
print(f"Message {msg.header.serial} calls {method}")
if method == 'write_data':
# body contains a FileDescriptor object, which we can convert to a file:
fd, = msg.body
with fd.to_file('w') as f:
f.write(f'Timestamp: {datetime.now()}')
# Leaving the with block will close the fd in this process
rep = new_method_return(msg, '') # Empty reply to say we're done
else:
rep = new_error(msg, SERVER_NAME + '.Error.NoMethod')
connection.send_message(rep)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1870296
jeepney-0.7.1/examples/blocking_secretstorage.py 0000644 0000000 0000000 00000002574 00000000000 016767 0 ustar 00 """Example accessing the SecretStorage DBus interface with blocking APIs
https://freedesktop.org/wiki/Specifications/secret-storage-spec/secrets-api-0.1.html#ref-dbus-api
"""
from jeepney import new_method_call, DBusAddress, Properties
from jeepney.io.blocking import open_dbus_connection
secrets = DBusAddress('/org/freedesktop/secrets',
bus_name= 'org.freedesktop.secrets',
interface='org.freedesktop.Secret.Service')
login_keyring = DBusAddress('/org/freedesktop/secrets/collection/login',
bus_name= 'org.freedesktop.secrets',
interface='org.freedesktop.Secret.Collection')
list_items = new_method_call(login_keyring, 'SearchItems', 'a{ss}',
([],))
conn = open_dbus_connection(bus='SESSION')
resp = conn.send_and_get_reply(Properties(secrets).get('Collections'))
print('Collections:', resp.body[0][1])
print('\nItems in login collection:')
all_items = conn.send_and_get_reply(list_items).body[0]
for obj_path in all_items:
item = DBusAddress(obj_path, 'org.freedesktop.secrets',
interface='org.freedesktop.Secret.Item')
props_resp = conn.send_and_get_reply(Properties(item).get_all())
props = dict(props_resp.body[0])
state = '(locked)' if props['Locked'][1] else ''
print(props['Label'][1], state)
conn.close()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/blocking_send_fd.py 0000644 0000000 0000000 00000002150 00000000000 015505 0 ustar 00 """Demonstrate sending a file descriptor
Start one of the _recv_fd.py scripts first, then run this.
Make a writable temporary file, send its file descriptor. The other process
writes into it before replying. This process can read what was written.
This works even though the temp file may never have a name on the filesystem
for the other process to open it.
"""
from tempfile import TemporaryFile
from jeepney import DBusAddress, new_method_call
from jeepney.io.blocking import open_dbus_connection
server = DBusAddress(
"/io/gitlab/takluyver/jeepney/examples/FDWriter",
bus_name="io.gitlab.takluyver.jeepney.examples.FDWriter",
)
with open_dbus_connection(enable_fds=True) as connection:
with TemporaryFile() as tf:
# TemporaryFile() has a .fileno() method, so it can be passed as the
# data for a file descriptor (h for handle).
msg = new_method_call(server, 'write_data', 'h', (tf,))
print("Sending:", tf)
reply = connection.send_and_get_reply(msg)
# Retrieve what the other process has written
tf.seek(0)
print("File contents:", tf.read())
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/blocking_server.py 0000644 0000000 0000000 00000003563 00000000000 015422 0 ustar 00 """A simple server built on Jeepney's blocking integration.
Start this, and then run blocking_server_client.py to send requests to it.
"""
import time
from jeepney import MessageType, HeaderFields, new_method_return, new_error
from jeepney.bus_messages import message_bus
from jeepney.io.blocking import open_dbus_connection
SERVER_NAME = "io.gitlab.takluyver.jeepney.examples.Server"
def slow_double(n):
time.sleep(5)
return n * 2
def double(n):
return n * 2
def divide(n, d):
return n / d
with open_dbus_connection() as connection:
print("My unique name is:", connection.unique_name)
# Request an additional name on the message bus
rep = connection.send_and_get_reply(message_bus.RequestName(SERVER_NAME))
if rep.body[0] == 1: # DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
print("Got name", SERVER_NAME)
while True:
msg = connection.receive()
if msg.header.message_type != MessageType.method_call:
print("Received non-method-call message:", msg)
method = msg.header.fields[HeaderFields.member]
print(f"Message {msg.header.serial} calls {method}")
# Dispatch to different methods
if method == 'slow_double':
res = slow_double(msg.body[0])
print(f"Delayed reply to {msg.header.serial}: {res}")
rep = new_method_return(msg, 'i', (res,))
elif method == 'double':
res = double(msg.body[0])
rep = new_method_return(msg, 'i', (res,))
elif method == 'divide':
try:
res = divide(*msg.body)
except ZeroDivisionError:
rep = new_error(msg, SERVER_NAME + ".Error.DivideByZero")
else:
rep = new_method_return(msg, 'd', (res,))
else:
rep = new_error(msg, SERVER_NAME + '.Error.NoMethod')
connection.send_message(rep)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/blocking_server_client.py 0000644 0000000 0000000 00000001502 00000000000 016747 0 ustar 00 """Simple client for the server in blocking_server.py
"""
import random
from time import sleep
from jeepney import DBusAddress, new_method_call
from jeepney.io.blocking import open_dbus_connection
server = DBusAddress(
"/io/gitlab/takluyver/jeepney/examples/Server",
bus_name="io.gitlab.takluyver.jeepney.examples.Server",
)
with open_dbus_connection() as connection:
for i in range(10):
n = random.randint(0, 5)
# Construct a new D-Bus message. new_method_call takes the address, the
# method name, the signature string, and a tuple of arguments.
msg = new_method_call(server, 'double', 'i', (n,))
print("Request:", n)
# Send the message and wait for the reply
reply = connection.send_and_get_reply(msg)
print('Result:', reply.body[0])
sleep(1)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/blocking_subscribe.py 0000644 0000000 0000000 00000003415 00000000000 016071 0 ustar 00 """
Example of subscribing to a D-Bus signal using blocking I/O.
This subscribes to the signal for a desktop notification being closed.
To try it, start this script, then trigger a desktop notification, and close it
somehow to trigger the signal. Use Ctrl-C to stop the script.
This example relies on the ``org.freedesktop.Notifications.NotificationClosed``
signal; some desktops may not support it. See the notification spec for more
details:
https://people.gnome.org/~mccann/docs/notification-spec/notification-spec-latest.html
Match rules are defined in the D-Bus specification:
https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules
"""
from collections import deque
from jeepney.bus_messages import MatchRule, message_bus
from jeepney.io.blocking import open_dbus_connection, Proxy
from jeepney.wrappers import DBusAddress
noti = DBusAddress('/org/freedesktop/Notifications',
bus_name='org.freedesktop.Notifications',
interface='org.freedesktop.Notifications')
connection = open_dbus_connection(bus="SESSION")
match_rule = MatchRule(
type="signal",
interface=noti.interface,
member="NotificationClosed",
path=noti.object_path,
)
# Tell the session bus to pass us matching signal messages:
bus_proxy = Proxy(message_bus, connection)
print("Match added?", bus_proxy.AddMatch(match_rule) == ())
print("Trigger a desktop notification (e.g. with notify-send) and then close it")
with connection.filter(match_rule) as queue:
signal_msg = connection.recv_until_filtered(queue)
reasons = {1: 'expiry', 2: 'dismissal', 3: 'dbus', '4': 'undefined'}
nid, reason_no = signal_msg.body
reason = reasons.get(reason_no, 'unknown')
print('Notification {} closed by: {}'.format(nid, reason))
connection.close()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/evil_client.py 0000644 0000000 0000000 00000002517 00000000000 014537 0 ustar 00 """Do not copy this example!
This is a deliberately broken example to test how D-Bus behaves when messages
are sent faster than they are handled. See other files in this folder for
useful examples of sending D-Bus messages nicely.
"""
import threading
import time
from jeepney import DBusAddress, new_method_call
from jeepney.integrate.blocking import connect_and_authenticate
server = DBusAddress(
"/io/gitlab/takluyver/jeepney/examples/Server",
bus_name="io.gitlab.takluyver.jeepney.examples.Server",
)
connection = connect_and_authenticate(bus='SESSION')
sending = True
def sender():
i = 0
while sending:
i += 1
n = i #random.randint(0, 5)
# Construct a new D-Bus message. new_method_call takes the address, the
# method name, the signature string, and a tuple of arguments.
msg = new_method_call(server, 'slow_double', 'is', (n, 'a' * 1024 * 300))
print(f"Request {i}: {n}")
connection.send(msg)
time.sleep(0.1)
send_thread = threading.Thread(target=sender)
send_thread.start()
def receiver():
while True:
msg = connection.receive()
print('Result:', msg.body[0])
# recv_thread = threading.Thread(target=receiver)
# recv_thread.start()
try:
receiver()
except KeyboardInterrupt:
pass
sending = False
send_thread.join()
connection.close()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/threading_recv_fd.py 0000644 0000000 0000000 00000003727 00000000000 015703 0 ustar 00 """Demonstrate receiving a file descriptor
Start this, and then run one of the _send_fd.py scripts to send requests.
"""
from datetime import datetime
import signal
from threading import Thread
from jeepney import MessageType, HeaderFields, new_method_return, new_error
from jeepney.bus_messages import message_bus
from jeepney.io.threading import (
open_dbus_connection, DBusRouter, Proxy, ReceiveStopped,
)
SERVER_NAME = "io.gitlab.takluyver.jeepney.examples.FDWriter"
def serve(conn, i):
while True:
try:
msg = conn.receive()
except ReceiveStopped:
return
if msg.header.message_type != MessageType.method_call:
print("Received non-method-call message:", msg)
method = msg.header.fields[HeaderFields.member]
print(f"Thread {i}: Message {msg.header.serial} calls {method}")
if method == 'write_data':
# body contains a FileDescriptor object, which we can convert to a file:
fd, = msg.body
with fd.to_file('w') as f:
f.write(f'Timestamp: {datetime.now()}, server thread {i}')
# Leaving the with block will close the fd in this process
rep = new_method_return(msg, '') # Empty reply to say we're done
else:
rep = new_error(msg, SERVER_NAME + '.Error.NoMethod')
conn.send(rep)
with open_dbus_connection(enable_fds=True) as conn:
# Request an additional name on the message bus
with DBusRouter(conn) as router:
bus_proxy = Proxy(message_bus, router, timeout=10)
if bus_proxy.RequestName(SERVER_NAME) == (1,):
# 1 == DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
print("Got name", SERVER_NAME)
threads = [Thread(target=serve, args=(conn, i)) for i in range(4)]
for t in threads:
t.start()
try:
signal.pause() # Wait for Ctrl-C
except KeyboardInterrupt:
pass
conn.interrupt()
for t in threads:
t.join()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/threading_send_fd.py 0000644 0000000 0000000 00000002754 00000000000 015674 0 ustar 00 """Demonstrate sending a file descriptor
Start one of the _recv_fd.py scripts first, then run this.
Make a writable temporary file, send its file descriptor. The other process
writes into it before replying. This process can read what was written.
This works even though the temp file may never have a name on the filesystem
for the other process to open it.
"""
from tempfile import TemporaryFile
from threading import Thread
import time
from jeepney import DBusAddress, new_method_call
from jeepney.io.threading import open_dbus_router
server = DBusAddress(
"/io/gitlab/takluyver/jeepney/examples/FDWriter",
bus_name="io.gitlab.takluyver.jeepney.examples.FDWriter",
)
def requests(router, i):
for _ in range(4):
with TemporaryFile() as tf:
# Construct a new D-Bus message. new_method_call takes the address, the
# method name, the signature string, and a tuple of arguments.
msg = new_method_call(server, 'write_data', 'h', (tf,))
print(f"Client thread {i} sending", tf)
# Send the message and wait for the reply
router.send_and_get_reply(msg)
# Retrieve what the other process has written
tf.seek(0)
print(f"Client thread {i} reads:", tf.read())
time.sleep(0.5)
with open_dbus_router(enable_fds=True) as router:
threads = [Thread(target=requests, args=(router, i)) for i in range(5)]
for t in threads:
t.start()
for t in threads:
t.join()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1880295
jeepney-0.7.1/examples/threading_server.py 0000644 0000000 0000000 00000004657 00000000000 015604 0 ustar 00 """A simple server built on Jeepney's blocking integration.
Start this, and then run blocking_server_client.py to send requests to it.
"""
import signal
from threading import Thread
import time
from jeepney import MessageType, HeaderFields, new_method_return, new_error
from jeepney.bus_messages import message_bus
from jeepney.io.threading import (
open_dbus_connection, DBusRouter, Proxy, ReceiveStopped,
)
SERVER_NAME = "io.gitlab.takluyver.jeepney.examples.Server"
def slow_double(n):
# Simulate something slow which releases the GIL so other threads can run
time.sleep(5)
return n * 2
def double(n):
return n * 2
def divide(n, d):
return n / d
def serve(conn, i):
while True:
try:
msg = conn.receive()
except ReceiveStopped:
return
if msg.header.message_type != MessageType.method_call:
print("Received non-method-call message:", msg)
method = msg.header.fields[HeaderFields.member]
print(f"Thread {i}: Message {msg.header.serial} calls {method}")
# Dispatch to different methods
if method == 'slow_double':
res = slow_double(msg.body[0])
print(f"Delayed reply to {msg.header.serial}: {res}")
rep = new_method_return(msg, 'i', (res,))
elif method == 'double':
res = double(msg.body[0])
rep = new_method_return(msg, 'i', (res,))
elif method == 'divide':
try:
res = divide(*msg.body)
except ZeroDivisionError:
rep = new_error(msg, SERVER_NAME + ".Error.DivideByZero")
else:
rep = new_method_return(msg, 'd', (res,))
else:
rep = new_error(msg, SERVER_NAME + '.Error.NoMethod')
conn.send(rep)
with open_dbus_connection() as conn:
print("My unique name is:", conn.unique_name)
# Request an additional name on the message bus
with DBusRouter(conn) as router:
bus_proxy = Proxy(message_bus, router, timeout=10)
if bus_proxy.RequestName(SERVER_NAME) == (1,):
# 1 == DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
print("Got name", SERVER_NAME)
threads = [Thread(target=serve, args=(conn, i)) for i in range(4)]
for t in threads:
t.start()
try:
signal.pause() # Wait for Ctrl-C
except KeyboardInterrupt:
pass
conn.interrupt()
for t in threads:
t.join()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1890295
jeepney-0.7.1/examples/threading_server_client.py 0000644 0000000 0000000 00000002052 00000000000 017125 0 ustar 00 """Make overlapping requests from several threads.
Use this alongside one of the _server.py examples
"""
import random
from threading import Thread
from jeepney import DBusAddress, new_method_call
from jeepney.io.threading import open_dbus_router
server = DBusAddress(
"/io/gitlab/takluyver/jeepney/examples/Server",
bus_name="io.gitlab.takluyver.jeepney.examples.Server",
)
def requests(router, i):
for _ in range(5):
n = random.randint(0, 5)
# Construct a new D-Bus message. new_method_call takes the address, the
# method name, the signature string, and a tuple of arguments.
msg = new_method_call(server, 'slow_double', 'i', (n,))
print(f"Thread {i} request:", n)
# Send the message and wait for the reply
reply = router.send_and_get_reply(msg)
print(f'Thread {i} result:', reply.body[0])
with open_dbus_router() as router:
threads = [Thread(target=requests, args=(router, i)) for i in range(6)]
for t in threads:
t.start()
for t in threads:
t.join()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1890295
jeepney-0.7.1/examples/trio_choose_file.py 0000644 0000000 0000000 00000002767 00000000000 015565 0 ustar 00 import trio
from jeepney import DBusAddress, new_method_call
from jeepney.bus_messages import message_bus, MatchRule
from jeepney.io.trio import open_dbus_router, Proxy
portal = DBusAddress(
object_path='/org/freedesktop/portal/desktop',
bus_name='org.freedesktop.portal.Desktop',
)
filechooser = portal.with_interface('org.freedesktop.portal.FileChooser')
token = 'file_choice_1'
async def choose_file():
async with open_dbus_router() as router:
sender_name = router.unique_name[1:].replace('.', '_')
handle = f"/org/freedesktop/portal/desktop/request/{sender_name}/{token}"
response_rule = MatchRule(
type='signal', interface='org.freedesktop.portal.Request', path=handle
)
await Proxy(message_bus, router).AddMatch(response_rule)
async with router.filter(response_rule) as responses:
# https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-method-org-freedesktop-portal-FileChooser.OpenFile
req = new_method_call(filechooser, 'OpenFile', 'ssa{sv}', (
# Parent window, title, options
'', 'Pick a file', {'handle_token': ('s', token)}
))
await router.send_and_get_reply(req)
response_signal_msg = await responses.receive()
response, results = response_signal_msg.body
if response == 0:
# print(results)
print("Chose file:", results['uris'][1][0])
if __name__ == '__main__':
trio.run(choose_file)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1890295
jeepney-0.7.1/examples/trio_notify.py 0000644 0000000 0000000 00000003455 00000000000 014611 0 ustar 00 import sys
sys.excepthook = sys.__excepthook__
import trio
from jeepney import MessageGenerator, new_method_call
from jeepney.io.trio import open_dbus_router, Proxy
# ---- Message generator, created by jeepney.bindgen ----
class Notifications(MessageGenerator):
interface = 'org.freedesktop.Notifications'
def __init__(self, object_path='/org/freedesktop/Notifications',
bus_name='org.freedesktop.Notifications'):
super().__init__(object_path=object_path, bus_name=bus_name)
def Notify(self, arg_0, arg_1, arg_2, arg_3, arg_4, arg_5, arg_6, arg_7):
return new_method_call(self, 'Notify', 'susssasa{sv}i',
(arg_0, arg_1, arg_2, arg_3, arg_4, arg_5, arg_6, arg_7))
def CloseNotification(self, arg_0):
return new_method_call(self, 'CloseNotification', 'u',
(arg_0,))
def GetCapabilities(self):
return new_method_call(self, 'GetCapabilities')
def GetServerInformation(self):
return new_method_call(self, 'GetServerInformation')
# ---- End auto generated code ----
async def send_notification():
async with open_dbus_router(bus='SESSION') as req:
proxy = Proxy(Notifications(), req)
resp = await proxy.Notify('jeepney_test', # App name
0, # Not replacing any previous notification
'', # Icon
'Hello, world!', # Summary
'This is an example notification from Jeepney & Trio',
[], {}, # Actions, hints
-1, # expire_timeout (-1 = default)
)
print('Notification ID:', resp[0])
if __name__ == '__main__':
trio.run(send_notification)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1890295
jeepney-0.7.1/examples/trio_recv_fd.py 0000644 0000000 0000000 00000003514 00000000000 014705 0 ustar 00 """Demonstrate receiving a file descriptor
Start this, and then run one of the _send_fd.py scripts to send requests.
"""
from datetime import datetime
import trio
from jeepney import MessageType, HeaderFields, new_method_return, new_error
from jeepney.bus_messages import message_bus
from jeepney.io.trio import (
open_dbus_connection, Proxy,
)
SERVER_NAME = "io.gitlab.takluyver.jeepney.examples.FDWriter"
async def serve(conn, i):
while True:
msg = await conn.receive()
if msg.header.message_type != MessageType.method_call:
print("Received non-method-call message:", msg)
continue
method = msg.header.fields[HeaderFields.member]
print(f"Task {i}: Message {msg.header.serial} calls {method}")
if method == 'write_data':
# body contains a FileDescriptor object, which we can convert to a file:
fd, = msg.body
with fd.to_file('w') as f:
f.write(f'Timestamp: {datetime.now()}, server task {i}')
# Leaving the with block will close the fd in this process
rep = new_method_return(msg, '') # Empty reply to say we're done
else:
rep = new_error(msg, SERVER_NAME + '.Error.NoMethod')
await conn.send(rep)
async def main():
conn = await open_dbus_connection(enable_fds=True)
# Request an additional name on the message bus
async with conn.router() as router:
bus_proxy = Proxy(message_bus, router)
with trio.fail_after(2):
reply, = await bus_proxy.RequestName(SERVER_NAME)
if reply == 1:
# 1 == DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
print("Got name", SERVER_NAME)
async with trio.open_nursery() as nursery:
for i in range(4):
nursery.start_soon(serve, conn, i)
trio.run(main)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1890295
jeepney-0.7.1/examples/trio_send_fd.py 0000644 0000000 0000000 00000002763 00000000000 014704 0 ustar 00 """Demonstrate sending a file descriptor
Start one of the _recv_fd.py scripts first, then run this.
Make a writable temporary file, send its file descriptor. The other process
writes into it before replying. This process can read what was written.
This works even though the temp file may never have a name on the filesystem
for the other process to open it.
"""
from tempfile import TemporaryFile
import trio
from jeepney import DBusAddress, new_method_call
from jeepney.io.trio import open_dbus_router
server = DBusAddress(
"/io/gitlab/takluyver/jeepney/examples/FDWriter",
bus_name="io.gitlab.takluyver.jeepney.examples.FDWriter",
)
async def requests(router, i):
for _ in range(4):
with TemporaryFile() as tf:
# Construct a new D-Bus message. new_method_call takes the address, the
# method name, the signature string, and a tuple of arguments.
msg = new_method_call(server, 'write_data', 'h', (tf,))
print(f"Client task {i} sending", tf)
# Send the message and wait for the reply
await router.send_and_get_reply(msg)
# Retrieve what the other process has written
tf.seek(0)
print(f"Client task {i} reads:", tf.read())
await trio.sleep(0.5)
async def main():
async with open_dbus_router(enable_fds=True) as router:
async with trio.open_nursery() as nursery:
for i in range(5):
nursery.start_soon(requests, router, i)
trio.run(main)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1627496089.4463944
jeepney-0.7.1/jeepney/__init__.py 0000644 0000000 0000000 00000000630 00000000000 013614 0 ustar 00 """Low-level, pure Python DBus protocol wrapper.
"""
from .auth import AuthenticationError, FDNegotiationError
from .low_level import (
Endianness, Header, HeaderFields, Message, MessageFlag, MessageType,
Parser, SizeLimitError,
)
from .bus import find_session_bus, find_system_bus
from .bus_messages import *
from .fds import FileDescriptor, NoFDError
from .wrappers import *
__version__ = '0.7.1'
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1900296
jeepney-0.7.1/jeepney/auth.py 0000644 0000000 0000000 00000011505 00000000000 013021 0 ustar 00 from binascii import hexlify
from enum import Enum
import os
from typing import Optional
def make_auth_external() -> bytes:
"""Prepare an AUTH command line with the current effective user ID.
This is the preferred authentication method for typical D-Bus connections
over a Unix domain socket.
"""
hex_uid = hexlify(str(os.geteuid()).encode('ascii'))
return b'AUTH EXTERNAL %b\r\n' % hex_uid
def make_auth_anonymous() -> bytes:
"""Format an AUTH command line for the ANONYMOUS mechanism
Jeepney's higher-level wrappers don't currently use this mechanism,
but third-party code may choose to.
See for details.
"""
from . import __version__
trace = hexlify(('Jeepney %s' % __version__).encode('ascii'))
return b'AUTH ANONYMOUS %s\r\n' % trace
BEGIN = b'BEGIN\r\n'
NEGOTIATE_UNIX_FD = b'NEGOTIATE_UNIX_FD\r\n'
class ClientState(Enum):
# States from the D-Bus spec (plus 'Success'). Not all used in Jeepney.
WaitingForData = 1
WaitingForOk = 2
WaitingForReject = 3
WaitingForAgreeUnixFD = 4
Success = 5
class AuthenticationError(ValueError):
"""Raised when DBus authentication fails"""
def __init__(self, data, msg="Authentication failed"):
self.msg = msg
self.data = data
def __str__(self):
return f"{self.msg}. Bus sent: {self.data!r}"
class FDNegotiationError(AuthenticationError):
"""Raised when file descriptor support is requested but not available"""
def __init__(self, data):
super().__init__(data, msg="File descriptor support not available")
class Authenticator:
"""Process data for the SASL authentication conversation
If enable_fds is True, this includes negotiating support for passing
file descriptors.
"""
def __init__(self, enable_fds=False):
self.enable_fds = enable_fds
self.buffer = bytearray()
self._to_send = b'\0' + make_auth_external()
self.state = ClientState.WaitingForOk
self.error = None
@property
def authenticated(self):
return self.state is ClientState.Success
def __iter__(self):
return iter(self.data_to_send, None)
def data_to_send(self) -> Optional[bytes]:
"""Get a line of data to send to the server
The data returned should be sent before waiting to receive data.
Returns empty bytes if waiting for more data from the server, and None
if authentication is finished (success or error).
Iterating over the Authenticator object will also yield these lines;
:meth:`feed` should be called with received data inside the loop.
"""
if self.authenticated or self.error:
return None
self._to_send, to_send = b'', self._to_send
return to_send
def process_line(self, line):
if self.state is ClientState.WaitingForOk:
if line.startswith(b'OK '):
if self.enable_fds:
return NEGOTIATE_UNIX_FD, ClientState.WaitingForAgreeUnixFD
else:
return BEGIN, ClientState.Success
# We only support EXTERNAL authentication, but if we allow others,
# 'REJECTED ' would tell us to try another one.
elif self.state is ClientState.WaitingForAgreeUnixFD:
if line.startswith(b'AGREE_UNIX_FD'):
return BEGIN, ClientState.Success
# The protocol allows us to continue if FD passing is rejected,
# but Jeepney assumes that if you enable FD support you need it,
# so we fail rather
self.error = line
raise FDNegotiationError(line)
self.error = line
raise AuthenticationError(line)
def feed(self, data: bytes):
"""Process received data
Raises AuthenticationError if the incoming data is not as expected for
successful authentication. The connection should then be abandoned.
"""
self.buffer += data
if b'\r\n' in self.buffer:
line, self.buffer = self.buffer.split(b'\r\n', 1)
if self.buffer:
# We only expect one line before we reply
raise AuthenticationError(self.buffer, "Unexpected data received")
self._to_send, self.state = self.process_line(line)
# Avoid consuming lots of memory if the server is not sending what we
# expect. There doesn't appear to be a specified maximum line length,
# but 8192 bytes leaves a sizeable margin over all the examples in the
# spec (all < 100 bytes per line).
elif len(self.buffer) > 8192:
raise AuthenticationError(
self.buffer, "Too much data received without line ending"
)
# Old name (behaviour on errors has changed, but should work for standard case)
SASLParser = Authenticator
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1900296
jeepney-0.7.1/jeepney/bindgen.py 0000644 0000000 0000000 00000007726 00000000000 013500 0 ustar 00 """Generate a wrapper class from DBus introspection data"""
import argparse
from textwrap import indent
import xml.etree.ElementTree as ET
from jeepney.wrappers import Introspectable
from jeepney.io.blocking import open_dbus_connection, Proxy
from jeepney import __version__
class Method:
def __init__(self, xml_node):
self.name = xml_node.attrib['name']
self.in_args = []
self.signature = []
for arg in xml_node.findall("arg[@direction='in']"):
try:
name = arg.attrib['name']
except KeyError:
name = 'arg{}'.format(len(self.in_args))
self.in_args.append(name)
self.signature.append(arg.attrib['type'])
def _make_code_noargs(self):
return ("def {name}(self):\n"
" return new_method_call(self, '{name}')\n").format(
name=self.name)
def make_code(self):
if not self.in_args:
return self._make_code_noargs()
args = ', '.join(self.in_args)
signature = ''.join(self.signature)
tuple = ('({},)' if len(self.in_args) == 1 else '({})').format(args)
return ("def {name}(self, {args}):\n"
" return new_method_call(self, '{name}', '{signature}',\n"
" {tuple})\n").format(
name=self.name, args=args, signature=signature, tuple=tuple
)
INTERFACE_CLASS_TEMPLATE = """
class {cls_name}(MessageGenerator):
interface = {interface!r}
def __init__(self, object_path={path!r},
bus_name={bus_name!r}):
super().__init__(object_path=object_path, bus_name=bus_name)
"""
class Interface:
def __init__(self, xml_node, path, bus_name):
self.name = xml_node.attrib['name']
self.path = path
self.bus_name = bus_name
self.methods = [Method(node) for node in xml_node.findall('method')]
def make_code(self):
cls_name = self.name.split('.')[-1]
chunks = [INTERFACE_CLASS_TEMPLATE.format(cls_name=cls_name,
interface=self.name, path=self.path, bus_name=self.bus_name)]
for method in self.methods:
chunks.append(indent(method.make_code(), ' ' * 4))
return '\n'.join(chunks)
MODULE_TEMPLATE = '''\
"""Auto-generated DBus bindings
Generated by jeepney version {version}
Object path: {path}
Bus name : {bus_name}
"""
from jeepney.wrappers import MessageGenerator, new_method_call
'''
# Jeepney already includes bindings for these common interfaces
IGNORE_INTERFACES = {
'org.freedesktop.DBus.Introspectable',
'org.freedesktop.DBus.Properties',
'org.freedesktop.DBus.Peer',
}
def code_from_xml(xml, path, bus_name, fh):
if isinstance(fh, (bytes, str)):
with open(fh, 'w') as f:
return code_from_xml(xml, path, bus_name, f)
root = ET.fromstring(xml)
fh.write(MODULE_TEMPLATE.format(version=__version__, path=path,
bus_name=bus_name))
i = 0
for interface_node in root.findall('interface'):
if interface_node.attrib['name'] in IGNORE_INTERFACES:
continue
fh.write(Interface(interface_node, path, bus_name).make_code())
i += 1
return i
def generate(path, name, output_file, bus='SESSION'):
conn = open_dbus_connection(bus)
introspectable = Proxy(Introspectable(path, name), conn)
xml, = introspectable.Introspect()
# print(xml)
n_interfaces = code_from_xml(xml, path, name, output_file)
print("Written {} interface wrappers to {}".format(n_interfaces, output_file))
def main():
ap = argparse.ArgumentParser()
ap.add_argument('-n', '--name', required=True)
ap.add_argument('-p', '--path', required=True)
ap.add_argument('--bus', default='SESSION')
ap.add_argument('-o', '--output')
args = ap.parse_args()
output = args.output or (args.path[1:].replace('/', '_') + '.py')
generate(args.path, args.name, output, args.bus)
if __name__ == '__main__':
main()
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1488127325.123201
jeepney-0.7.1/jeepney/bus.py 0000644 0000000 0000000 00000003431 00000000000 012650 0 ustar 00 import os
import re
_escape_pat = re.compile(r'%([0-9A-Fa-f]{2})')
def unescape(v):
def repl(match):
n = int(match.group(1), base=16)
return chr(n)
return _escape_pat.sub(repl, v)
def parse_addresses(s):
for addr in s.split(';'):
transport, info = addr.split(':', 1)
kv = {}
for x in info.split(','):
k, v = x.split('=', 1)
kv[k] = unescape(v)
yield (transport, kv)
SUPPORTED_TRANSPORTS = ('unix',)
def get_connectable_addresses(addr):
unsupported_transports = set()
found = False
for transport, kv in parse_addresses(addr):
if transport not in SUPPORTED_TRANSPORTS:
unsupported_transports.add(transport)
elif transport == 'unix':
if 'abstract' in kv:
yield '\0' + kv['abstract']
found = True
elif 'path' in kv:
yield kv['path']
found = True
if not found:
raise RuntimeError("DBus transports ({}) not supported. Supported: {}"
.format(unsupported_transports, SUPPORTED_TRANSPORTS))
def find_session_bus():
addr = os.environ['DBUS_SESSION_BUS_ADDRESS']
return next(get_connectable_addresses(addr))
# TODO: fallbacks to X, filesystem
def find_system_bus():
addr = os.environ.get('DBUS_SYSTEM_BUS_ADDRESS', '') \
or 'unix:path=/var/run/dbus/system_bus_socket'
return next(get_connectable_addresses(addr))
def get_bus(addr):
if addr == 'SESSION':
return find_session_bus()
elif addr == 'SYSTEM':
return find_system_bus()
else:
return next(get_connectable_addresses(addr))
if __name__ == '__main__':
print('System bus at:', find_system_bus())
print('Session bus at:', find_session_bus())
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1900296
jeepney-0.7.1/jeepney/bus_messages.py 0000644 0000000 0000000 00000017714 00000000000 014550 0 ustar 00 """Messages for talking to the DBus daemon itself
Generated by jeepney.bindgen and modified by hand.
"""
from .low_level import Message, MessageType, HeaderFields
from .wrappers import MessageGenerator, new_method_call
__all__ = [
'DBusNameFlags',
'DBus',
'message_bus',
'Monitoring',
'Stats',
'MatchRule',
]
class DBusNameFlags:
allow_replacement = 1
replace_existing = 2
do_not_queue = 4
class DBus(MessageGenerator):
"""Messages to talk to the message bus
"""
interface = 'org.freedesktop.DBus'
def __init__(self, object_path='/org/freedesktop/DBus',
bus_name='org.freedesktop.DBus'):
super().__init__(object_path=object_path, bus_name=bus_name)
def Hello(self):
return new_method_call(self, 'Hello')
def RequestName(self, name, flags=0):
return new_method_call(self, 'RequestName', 'su', (name, flags))
def ReleaseName(self, name):
return new_method_call(self, 'ReleaseName', 's', (name,))
def StartServiceByName(self, name):
return new_method_call(self, 'StartServiceByName', 'su',
(name, 0))
def UpdateActivationEnvironment(self, env):
return new_method_call(self, 'UpdateActivationEnvironment', 'a{ss}',
(env,))
def NameHasOwner(self, name):
return new_method_call(self, 'NameHasOwner', 's', (name,))
def ListNames(self):
return new_method_call(self, 'ListNames')
def ListActivatableNames(self):
return new_method_call(self, 'ListActivatableNames')
def AddMatch(self, rule):
"""*rule* can be a str or a :class:`MatchRule` instance"""
if isinstance(rule, MatchRule):
rule = rule.serialise()
return new_method_call(self, 'AddMatch', 's', (rule,))
def RemoveMatch(self, rule):
if isinstance(rule, MatchRule):
rule = rule.serialise()
return new_method_call(self, 'RemoveMatch', 's', (rule,))
def GetNameOwner(self, name):
return new_method_call(self, 'GetNameOwner', 's', (name,))
def ListQueuedOwners(self, name):
return new_method_call(self, 'ListQueuedOwners', 's', (name,))
def GetConnectionUnixUser(self, name):
return new_method_call(self, 'GetConnectionUnixUser', 's', (name,))
def GetConnectionUnixProcessID(self, name):
return new_method_call(self, 'GetConnectionUnixProcessID', 's', (name,))
def GetAdtAuditSessionData(self, name):
return new_method_call(self, 'GetAdtAuditSessionData', 's', (name,))
def GetConnectionSELinuxSecurityContext(self, name):
return new_method_call(self, 'GetConnectionSELinuxSecurityContext', 's',
(name,))
def ReloadConfig(self):
return new_method_call(self, 'ReloadConfig')
def GetId(self):
return new_method_call(self, 'GetId')
def GetConnectionCredentials(self, name):
return new_method_call(self, 'GetConnectionCredentials', 's', (name,))
message_bus = DBus()
class Monitoring(MessageGenerator):
interface = 'org.freedesktop.DBus.Monitoring'
def __init__(self, object_path='/org/freedesktop/DBus',
bus_name='org.freedesktop.DBus'):
super().__init__(object_path=object_path, bus_name=bus_name)
def BecomeMonitor(self, rules):
"""Convert this connection to a monitor connection (advanced)"""
return new_method_call(self, 'BecomeMonitor', 'asu', (rules, 0))
class Stats(MessageGenerator):
interface = 'org.freedesktop.DBus.Debug.Stats'
def __init__(self, object_path='/org/freedesktop/DBus',
bus_name='org.freedesktop.DBus'):
super().__init__(object_path=object_path, bus_name=bus_name)
def GetStats(self):
return new_method_call(self, 'GetStats')
def GetConnectionStats(self, arg0):
return new_method_call(self, 'GetConnectionStats', 's',
(arg0,))
def GetAllMatchRules(self):
return new_method_call(self, 'GetAllMatchRules')
class MatchRule:
"""Construct a match rule to subscribe to DBus messages.
e.g.::
mr = MatchRule(
interface='org.freedesktop.DBus',
member='NameOwnerChanged',
type='signal'
)
msg = message_bus.AddMatch(mr)
# Send this message to subscribe to the signal
"""
def __init__(self, *, type=None, sender=None, interface=None, member=None,
path=None, path_namespace=None, destination=None,
eavesdrop=False):
if isinstance(type, str):
type = MessageType[type]
self.message_type = type
fields = {
'sender': sender,
'interface': interface,
'member': member,
'path': path,
'destination': destination,
}
self.header_fields = {
k: v for (k, v) in fields.items() if (v is not None)
}
self.path_namespace = path_namespace
self.eavesdrop = eavesdrop
self.arg_conditions = {}
def add_arg_condition(self, argno: int, value: str, kind='string'):
"""Add a condition for a particular argument
argno: int, 0-63
kind: 'string', 'path', 'namespace'
"""
if kind not in {'string', 'path', 'namespace'}:
raise ValueError("kind={!r}".format(kind))
if kind == 'namespace' and argno != 0:
raise ValueError("argno must be 0 for kind='namespace'")
self.arg_conditions[argno] = (value, kind)
def serialise(self) -> str:
"""Convert to a string to use in an AddMatch call to the message bus"""
pairs = list(self.header_fields.items())
if self.message_type:
pairs.append(('type', self.message_type.name))
if self.eavesdrop:
pairs.append(('eavesdrop', 'true'))
for argno, (val, kind) in self.arg_conditions.items():
if kind == 'string':
kind = ''
pairs.append((f'arg{argno}{kind}', val))
# Quoting rules: single quotes ('') needed if the value contains a comma.
# A literal ' can only be represented outside single quotes, by
# backslash-escaping it. No escaping inside the quotes.
# The simplest way to handle this is to use '' around every value, and
# use '\'' (end quote, escaped ', restart quote) for literal ' .
return ','.join(
"{}='{}'".format(k, v.replace("'", r"'\''")) for (k, v) in pairs
)
def matches(self, msg: Message) -> bool:
"""Returns True if msg matches this rule"""
h = msg.header
if (self.message_type is not None) and h.message_type != self.message_type:
return False
for field, expected in self.header_fields.items():
if h.fields.get(HeaderFields[field], None) != expected:
return False
if self.path_namespace is not None:
path = h.fields.get(HeaderFields.path, '\0')
path_ns = self.path_namespace.rstrip('/')
if not ((path == path_ns) or path.startswith(path_ns + '/')):
return False
for argno, (expected, kind) in self.arg_conditions.items():
if argno >= len(msg.body):
return False
arg = msg.body[argno]
if not isinstance(arg, str):
return False
if kind == 'string':
if arg != expected:
return False
elif kind == 'path':
if not (
(arg == expected)
or (expected.endswith('/') and arg.startswith(expected))
or (arg.endswith('/') and expected.startswith(arg))
):
return False
elif kind == 'namespace':
if not (
(arg == expected)
or arg.startswith(expected + '.')
):
return False
return True
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1900296
jeepney-0.7.1/jeepney/fds.py 0000644 0000000 0000000 00000011700 00000000000 012631 0 ustar 00 import array
import os
import socket
from warnings import warn
class NoFDError(RuntimeError):
"""Raised by :class:`FileDescriptor` methods if it was already closed/converted
"""
pass
class FileDescriptor:
"""A file descriptor received in a D-Bus message
This wrapper helps ensure that the file descriptor is closed exactly once.
If you don't explicitly convert or close the FileDescriptor object, it will
close its file descriptor when it goes out of scope, and emit a
ResourceWarning.
"""
__slots__ = ('_fd',)
_CLOSED = -1
_CONVERTED = -2
def __init__(self, fd):
self._fd = fd
def __repr__(self):
detail = self._fd
if self._fd == self._CLOSED:
detail = 'closed'
elif self._fd == self._CONVERTED:
detail = 'converted'
return f""
def close(self):
"""Close the file descriptor
This can safely be called multiple times, but will raise RuntimeError
if called after converting it with one of the ``to_*`` methods.
This object can also be used in a ``with`` block, to close it on
leaving the block.
"""
if self._fd == self._CLOSED:
pass
elif self._fd == self._CONVERTED:
raise NoFDError("Can't close FileDescriptor after converting it")
else:
self._fd, fd = self._CLOSED, self._fd
os.close(fd)
def __enter__(self):
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.close()
def __del__(self):
if self._fd >= 0:
warn(
f'FileDescriptor ({self._fd}) was neither closed nor converted',
ResourceWarning, stacklevel=2, source=self
)
self.close()
def _check(self):
if self._fd < 0:
detail = 'closed' if self._fd == self._CLOSED else 'converted'
raise NoFDError(f'FileDescriptor object was already {detail}')
def fileno(self):
"""Get the integer file descriptor
This does not change the state of the :class:`FileDescriptor` object,
unlike the ``to_*`` methods.
"""
self._check()
return self._fd
def to_raw_fd(self):
"""Convert to the low-level integer file descriptor::
raw_fd = fd.to_raw_fd()
os.write(raw_fd, b'xyz')
os.close(raw_fd)
The :class:`FileDescriptor` can't be used after calling this. The caller
is responsible for closing the file descriptor.
"""
self._check()
self._fd, fd = self._CONVERTED, self._fd
return fd
def to_file(self, mode, buffering=-1, encoding=None, errors=None, newline=None):
"""Convert to a Python file object::
with fd.to_file('w') as f:
f.write('xyz')
The arguments are the same as for the builtin :func:`open` function.
The :class:`FileDescriptor` can't be used after calling this. Closing
the file object will also close the file descriptor.
"""
self._check()
f = open(
self._fd, mode, buffering=buffering,
encoding=encoding, errors=errors, newline=newline
)
self._fd = self._CONVERTED
return f
def to_socket(self):
"""Convert to a socket object
This returns a standard library :func:`socket.socket` object::
with fd.to_socket() as sock:
b = sock.sendall(b'xyz')
The wrapper object can't be used after calling this. Closing the socket
object will also close the file descriptor.
"""
from socket import socket
self._check()
s = socket(fileno=self._fd)
self._fd = self._CONVERTED
return s
@classmethod
def from_ancdata(cls, ancdata) -> ['FileDescriptor']:
"""Make a list of FileDescriptor from received file descriptors
ancdata is a list of ancillary data tuples as returned by socket.recvmsg()
"""
fds = array.array("i") # Array of ints
for cmsg_level, cmsg_type, data in ancdata:
if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
# Append data, ignoring any truncated integers at the end.
fds.frombytes(data[:len(data) - (len(data) % fds.itemsize)])
return [cls(i) for i in fds]
_fds_buf_size_cache = None
def fds_buf_size():
# If there may be file descriptors, we try to read 1 message at a time.
# The reference implementation of D-Bus defaults to allowing 16 FDs per
# message, and the Linux kernel currently allows 253 FDs per sendmsg()
# call. So hopefully allowing 256 FDs per recvmsg() will always suffice.
global _fds_buf_size_cache
if _fds_buf_size_cache is None:
maxfds = 256
fd_size = array.array('i').itemsize
_fds_buf_size_cache = socket.CMSG_SPACE(maxfds * fd_size)
return _fds_buf_size_cache
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1900296
jeepney-0.7.1/jeepney/integrate/__init__.py 0000644 0000000 0000000 00000000051 00000000000 015573 0 ustar 00 """Deprecated: use jeepney.io instead"""
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1900296
jeepney-0.7.1/jeepney/integrate/asyncio.py 0000644 0000000 0000000 00000006011 00000000000 015503 0 ustar 00 """Deprecated: use jeepney.io.asyncio instead"""
import asyncio
from warnings import warn
from jeepney import Parser, MessageType
from jeepney.auth import AuthenticationError, BEGIN, make_auth_external, SASLParser
from jeepney.bus import get_bus
from jeepney.bus_messages import message_bus
from jeepney.routing import Router
from jeepney.wrappers import ProxyBase
warn("jeepney.integrate.asyncio is deprecated: please use jeepney.io.asyncio "
"instead.", stacklevel=2)
class DBusProtocol(asyncio.Protocol):
def __init__(self):
self.auth_parser = SASLParser()
self.parser = Parser()
self.router = Router(asyncio.Future)
self.authentication = asyncio.Future()
self.unique_name = None
def connection_made(self, transport):
self.transport = transport
self.transport.write(b'\0' + make_auth_external())
def _authenticated(self):
self.transport.write(BEGIN)
self.authentication.set_result(True)
self.data_received = self.data_received_post_auth
self.data_received(self.auth_parser.buffer)
def data_received(self, data):
self.auth_parser.feed(data)
if self.auth_parser.authenticated:
self._authenticated()
elif self.auth_parser.error:
self.authentication.set_exception(AuthenticationError(self.auth_parser.error))
def data_received_post_auth(self, data):
for msg in self.parser.feed(data):
self.router.incoming(msg)
def send_message(self, message):
if not self.authentication.done():
raise RuntimeError("Wait for authentication before sending messages")
future = self.router.outgoing(message)
data = message.serialise()
self.transport.write(data)
return future
async def send_and_get_reply(self, message):
if message.header.message_type != MessageType.method_call:
raise TypeError("Only method call messages have replies")
return await self.send_message(message)
class Proxy(ProxyBase):
"""An asyncio proxy for calling D-Bus methods
:param msggen: A message generator object.
:param DBusProtocol proto: Protocol object to send and receive messages.
"""
def __init__(self, msggen, protocol):
super().__init__(msggen)
self._protocol = protocol
def __repr__(self):
return 'Proxy({}, {})'.format(self._msggen, self._protocol)
def _method_call(self, make_msg):
async def inner(*args, **kwargs):
msg = make_msg(*args, **kwargs)
assert msg.header.message_type is MessageType.method_call
return await self._protocol.send_and_get_reply(msg)
return inner
async def connect_and_authenticate(bus='SESSION', loop=None):
if loop is None:
loop = asyncio.get_event_loop()
(t, p) = await loop.create_unix_connection(DBusProtocol, path=get_bus(bus))
await p.authentication
bus = Proxy(message_bus, p)
hello_reply = await bus.Hello()
p.unique_name = hello_reply[0]
return (t, p)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/integrate/blocking.py 0000644 0000000 0000000 00000001003 00000000000 015622 0 ustar 00 """Deprecated: use jeepney.io.blocking instead"""
from warnings import warn
from jeepney.io.blocking import *
warn("jeepney.integrate.blocking is deprecated: please use jeepney.io.blocking "
"instead.", stacklevel=2)
def connect_and_authenticate(bus='SESSION') -> DBusConnection:
conn = open_dbus_connection(bus)
conn._unwrap_reply = True # Backward compatible behaviour
return conn
if __name__ == '__main__':
conn = connect_and_authenticate()
print("Unique name:", conn.unique_name)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/integrate/tests/__init__.py 0000644 0000000 0000000 00000000000 00000000000 016727 0 ustar 00 ././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/integrate/tests/test_asyncio.py 0000644 0000000 0000000 00000002515 00000000000 017711 0 ustar 00 import asyncio
import pytest
from jeepney import DBusAddress, new_method_call
from jeepney.bus_messages import message_bus
from jeepney.integrate.asyncio import (
connect_and_authenticate, Proxy
)
from jeepney.io.tests.utils import have_session_bus
pytestmark = [
pytest.mark.asyncio,
pytest.mark.skipif(
not have_session_bus, reason="Tests require DBus session bus"
),
]
@pytest.fixture()
async def session_proto():
transport, proto = await connect_and_authenticate(bus='SESSION')
yield proto
transport.close()
async def test_connect_old(session_proto):
assert session_proto.unique_name.startswith(':')
bus_peer = DBusAddress(
bus_name='org.freedesktop.DBus',
object_path='/org/freedesktop/DBus',
interface='org.freedesktop.DBus.Peer'
)
async def test_send_and_get_reply_old(session_proto):
ping_call = new_method_call(bus_peer, 'Ping')
reply_body = await asyncio.wait_for(
session_proto.send_message(ping_call), timeout=5
)
assert reply_body == ()
async def test_proxy_old(session_proto):
proxy = Proxy(message_bus, session_proto)
name = "io.gitlab.takluyver.jeepney.examples.Server"
res = await proxy.RequestName(name)
assert res in {(1,), (2,)} # 1: got the name, 2: queued
has_owner, = await proxy.NameHasOwner(name)
assert has_owner is True
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/integrate/tornado.py 0000644 0000000 0000000 00000001013 00000000000 015501 0 ustar 00 """Deprecated: use jeepney.io.tornado instead"""
from warnings import warn
from jeepney.io.tornado import *
warn("jeepney.integrate.tornado is deprecated. Tornado is now built on top of "
"asyncio, so please use jeepney.io.asyncio instead.", stacklevel=2)
async def connect_and_authenticate(bus='SESSION'):
conn = await open_dbus_connection(bus)
return DBusRouter(conn)
if __name__ == '__main__':
rtr = IOLoop.current().run_sync(connect_and_authenticate)
print("Unique name is:", rtr.unique_name)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/io/__init__.py 0000644 0000000 0000000 00000000041 00000000000 014217 0 ustar 00 from .common import RouterClosed
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1627495310.1410055
jeepney-0.7.1/jeepney/io/asyncio.py 0000644 0000000 0000000 00000016706 00000000000 014144 0 ustar 00 import asyncio
import contextlib
from itertools import count
from typing import Optional
from jeepney.auth import Authenticator, BEGIN
from jeepney.bus import get_bus
from jeepney import Message, MessageType, Parser
from jeepney.wrappers import ProxyBase, unwrap_msg
from jeepney.bus_messages import message_bus
from .common import (
MessageFilters, FilterHandle, ReplyMatcher, RouterClosed, check_replyable,
)
class DBusConnection:
"""A plain D-Bus connection with no matching of replies.
This doesn't run any separate tasks: sending and receiving are done in
the task that calls those methods. It's suitable for implementing servers:
several worker tasks can receive requests and send replies.
For a typical client pattern, see :class:`DBusRouter`.
"""
def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
self.reader = reader
self.writer = writer
self.parser = Parser()
self.outgoing_serial = count(start=1)
self.unique_name = None
self.send_lock = asyncio.Lock()
async def send(self, message: Message, *, serial=None):
"""Serialise and send a :class:`~.Message` object"""
async with self.send_lock:
if serial is None:
serial = next(self.outgoing_serial)
self.writer.write(message.serialise(serial))
await self.writer.drain()
async def receive(self) -> Message:
"""Return the next available message from the connection"""
while True:
msg = self.parser.get_next_message()
if msg is not None:
return msg
b = await self.reader.read(4096)
if not b:
raise EOFError
self.parser.add_data(b)
async def close(self):
"""Close the D-Bus connection"""
self.writer.close()
await self.writer.wait_closed()
async def __aenter__(self):
return self
async def __aexit__(self, exc_type, exc_val, exc_tb):
await self.close()
async def open_dbus_connection(bus='SESSION'):
"""Open a plain D-Bus connection
:return: :class:`DBusConnection`
"""
bus_addr = get_bus(bus)
reader, writer = await asyncio.open_unix_connection(bus_addr)
# Authentication flow
authr = Authenticator()
for req_data in authr:
writer.write(req_data)
await writer.drain()
b = await reader.read(1024)
if not b:
raise EOFError("Socket closed before authentication")
authr.feed(b)
writer.write(BEGIN)
await writer.drain()
# Authentication finished
conn = DBusConnection(reader, writer)
# Say *Hello* to the message bus - this must be the first message, and the
# reply gives us our unique name.
async with DBusRouter(conn) as router:
reply_body = await asyncio.wait_for(Proxy(message_bus, router).Hello(), 10)
conn.unique_name = reply_body[0]
return conn
class DBusRouter:
"""A 'client' D-Bus connection which can wait for a specific reply.
This runs a background receiver task, and makes it possible to send a
request and wait for the relevant reply.
"""
_nursery_mgr = None
_send_cancel_scope = None
_rcv_cancel_scope = None
def __init__(self, conn: DBusConnection):
self._conn = conn
self._replies = ReplyMatcher()
self._filters = MessageFilters()
self._rcv_task = asyncio.create_task(self._receiver())
@property
def unique_name(self):
return self._conn.unique_name
async def send(self, message, *, serial=None):
"""Send a message, don't wait for a reply"""
await self._conn.send(message, serial=serial)
async def send_and_get_reply(self, message) -> Message:
"""Send a method call message and wait for the reply
Returns the reply message (method return or error message type).
"""
check_replyable(message)
if self._rcv_task.done():
raise RouterClosed("This DBusRouter has stopped")
serial = next(self._conn.outgoing_serial)
with self._replies.catch(serial, asyncio.Future()) as reply_fut:
await self.send(message, serial=serial)
return (await reply_fut)
def filter(self, rule, *, queue: Optional[asyncio.Queue] =None, bufsize=1):
"""Create a filter for incoming messages
Usage::
with router.filter(rule) as queue:
matching_msg = await queue.get()
:param MatchRule rule: Catch messages matching this rule
:param asyncio.Queue queue: Send matching messages here
:param int bufsize: If no queue is passed in, create one with this size
"""
return FilterHandle(self._filters, rule, queue or asyncio.Queue(bufsize))
async def __aenter__(self):
return self
async def __aexit__(self, exc_type, exc_val, exc_tb):
if self._rcv_task.done():
self._rcv_task.result() # Throw exception if receive task failed
else:
self._rcv_task.cancel()
with contextlib.suppress(asyncio.CancelledError):
await self._rcv_task
return False
# Code to run in receiver task ------------------------------------
def _dispatch(self, msg: Message):
"""Handle one received message"""
if self._replies.dispatch(msg):
return
for filter in list(self._filters.matches(msg)):
try:
filter.queue.put_nowait(msg)
except asyncio.QueueFull:
pass
async def _receiver(self):
"""Receiver loop - runs in a separate task"""
try:
while True:
msg = await self._conn.receive()
self._dispatch(msg)
finally:
# Send errors to any tasks still waiting for a message.
self._replies.drop_all()
class open_dbus_router:
"""Open a D-Bus 'router' to send and receive messages
Use as an async context manager::
async with open_dbus_router() as router:
...
"""
conn = None
req_ctx = None
def __init__(self, bus='SESSION'):
self.bus = bus
async def __aenter__(self):
self.conn = await open_dbus_connection(self.bus)
self.req_ctx = DBusRouter(self.conn)
return await self.req_ctx.__aenter__()
async def __aexit__(self, exc_type, exc_val, exc_tb):
await self.req_ctx.__aexit__(exc_type, exc_val, exc_tb)
await self.conn.close()
class Proxy(ProxyBase):
"""An asyncio proxy for calling D-Bus methods
You can call methods on the proxy object, such as ``await bus_proxy.Hello()``
to make a method call over D-Bus and wait for a reply. It will either
return a tuple of returned data, or raise :exc:`.DBusErrorResponse`.
The methods available are defined by the message generator you wrap.
:param msggen: A message generator object.
:param ~asyncio.DBusRouter router: Router to send and receive messages.
"""
def __init__(self, msggen, router):
super().__init__(msggen)
self._router = router
def __repr__(self):
return 'Proxy({}, {})'.format(self._msggen, self._router)
def _method_call(self, make_msg):
async def inner(*args, **kwargs):
msg = make_msg(*args, **kwargs)
assert msg.header.message_type is MessageType.method_call
reply = await self._router.send_and_get_reply(msg)
return unwrap_msg(reply)
return inner
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/io/blocking.py 0000644 0000000 0000000 00000027277 00000000000 014274 0 ustar 00 """Synchronous IO wrappers around jeepney
"""
import array
from collections import deque
from errno import ECONNRESET
import functools
from itertools import count
import os
from selectors import DefaultSelector, EVENT_READ
import socket
import time
from typing import Optional
from jeepney import Parser, Message, MessageType, HeaderFields
from jeepney.auth import Authenticator, BEGIN
from jeepney.bus import get_bus
from jeepney.fds import FileDescriptor, fds_buf_size
from jeepney.wrappers import ProxyBase, unwrap_msg
from jeepney.routing import Router
from jeepney.bus_messages import message_bus
from .common import MessageFilters, FilterHandle, check_replyable
__all__ = [
'open_dbus_connection',
'DBusConnection',
'Proxy',
]
class _Future:
def __init__(self):
self._result = None
def done(self):
return bool(self._result)
def set_exception(self, exception):
self._result = (False, exception)
def set_result(self, result):
self._result = (True, result)
def result(self):
success, value = self._result
if success:
return value
raise value
def timeout_to_deadline(timeout):
if timeout is not None:
return time.monotonic() + timeout
return None
def deadline_to_timeout(deadline):
if deadline is not None:
return max(deadline - time.monotonic(), 0.)
return None
class DBusConnectionBase:
"""Connection machinery shared by this module and threading"""
def __init__(self, sock: socket.socket, enable_fds=False):
self.sock = sock
self.enable_fds = enable_fds
self.parser = Parser()
self.outgoing_serial = count(start=1)
self.selector = DefaultSelector()
self.select_key = self.selector.register(sock, EVENT_READ)
self.unique_name = None
def __enter__(self):
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.close()
return False
def _serialise(self, message: Message, serial) -> (bytes, Optional[array.array]):
if serial is None:
serial = next(self.outgoing_serial)
fds = array.array('i') if self.enable_fds else None
data = message.serialise(serial=serial, fds=fds)
return data, fds
def _send_with_fds(self, data, fds):
bytes_sent = self.sock.sendmsg(
[data], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds)]
)
# If sendmsg succeeds, I think ancillary data has been sent atomically?
# So now we just need to send any leftover normal data.
if bytes_sent < len(data):
self.sock.sendall(data[bytes_sent:])
def _receive(self, deadline):
while True:
msg = self.parser.get_next_message()
if msg is not None:
return msg
b, fds = self._read_some_data(timeout=deadline_to_timeout(deadline))
self.parser.add_data(b, fds=fds)
def _read_some_data(self, timeout=None):
for key, ev in self.selector.select(timeout):
if key == self.select_key:
if self.enable_fds:
return self._read_with_fds()
else:
return unwrap_read(self.sock.recv(4096)), []
raise TimeoutError
def _read_with_fds(self):
nbytes = self.parser.bytes_desired()
data, ancdata, flags, _ = self.sock.recvmsg(nbytes, fds_buf_size())
if flags & getattr(socket, 'MSG_CTRUNC', 0):
self.close()
raise RuntimeError("Unable to receive all file descriptors")
return unwrap_read(data), FileDescriptor.from_ancdata(ancdata)
def close(self):
"""Close the connection"""
self.selector.close()
self.sock.close()
class DBusConnection(DBusConnectionBase):
def __init__(self, sock: socket.socket, enable_fds=False):
super().__init__(sock, enable_fds)
self._unwrap_reply = False
# Message routing machinery
self.router = Router(_Future) # Old interface, for backwards compat
self._filters = MessageFilters()
# Say Hello, get our unique name
self.bus_proxy = Proxy(message_bus, self)
hello_reply = self.bus_proxy.Hello()
self.unique_name = hello_reply[0]
def send(self, message: Message, serial=None):
"""Serialise and send a :class:`~.Message` object"""
data, fds = self._serialise(message, serial)
if fds:
self._send_with_fds(data, fds)
else:
self.sock.sendall(data)
send_message = send # Backwards compatibility
def receive(self, *, timeout=None) -> Message:
"""Return the next available message from the connection
If the data is ready, this will return immediately, even if timeout<=0.
Otherwise, it will wait for up to timeout seconds, or indefinitely if
timeout is None. If no message comes in time, it raises TimeoutError.
"""
return self._receive(timeout_to_deadline(timeout))
def recv_messages(self, *, timeout=None):
"""Receive one message and apply filters
See :meth:`filter`. Returns nothing.
"""
msg = self.receive(timeout=timeout)
self.router.incoming(msg)
for filter in self._filters.matches(msg):
filter.queue.append(msg)
def send_and_get_reply(self, message, *, timeout=None, unwrap=None):
"""Send a message, wait for the reply and return it
Filters are applied to other messages received before the reply -
see :meth:`add_filter`.
"""
check_replyable(message)
deadline = timeout_to_deadline(timeout)
if unwrap is None:
unwrap = self._unwrap_reply
serial = next(self.outgoing_serial)
self.send_message(message, serial=serial)
while True:
msg_in = self.receive(timeout=deadline_to_timeout(deadline))
reply_to = msg_in.header.fields.get(HeaderFields.reply_serial, -1)
if reply_to == serial:
if unwrap:
return unwrap_msg(msg_in)
return msg_in
# Not the reply
self.router.incoming(msg_in)
for filter in self._filters.matches(msg_in):
filter.queue.append(msg_in)
def filter(self, rule, *, queue: Optional[deque] =None, bufsize=1):
"""Create a filter for incoming messages
Usage::
with conn.filter(rule) as matches:
# matches is a deque containing matched messages
matching_msg = conn.recv_until_filtered(matches)
:param jeepney.MatchRule rule: Catch messages matching this rule
:param collections.deque queue: Matched messages will be added to this
:param int bufsize: If no deque is passed in, create one with this size
"""
if queue is None:
queue = deque(maxlen=bufsize)
return FilterHandle(self._filters, rule, queue)
def recv_until_filtered(self, queue, *, timeout=None) -> Message:
"""Process incoming messages until one is filtered into queue
Pops the message from queue and returns it, or raises TimeoutError if
the optional timeout expires. Without a timeout, this is equivalent to::
while len(queue) == 0:
conn.recv_messages()
return queue.popleft()
In the other I/O modules, there is no need for this, because messages
are placed in queues by a separate task.
:param collections.deque queue: A deque connected by :meth:`filter`
:param float timeout: Maximum time to wait in seconds
"""
deadline = timeout_to_deadline(timeout)
while len(queue) == 0:
self.recv_messages(timeout=deadline_to_timeout(deadline))
return queue.popleft()
class Proxy(ProxyBase):
"""A blocking proxy for calling D-Bus methods
You can call methods on the proxy object, such as ``bus_proxy.Hello()``
to make a method call over D-Bus and wait for a reply. It will either
return a tuple of returned data, or raise :exc:`.DBusErrorResponse`.
The methods available are defined by the message generator you wrap.
You can set a time limit on a call by passing ``_timeout=`` in the method
call, or set a default when creating the proxy. The ``_timeout`` argument
is not passed to the message generator.
All timeouts are in seconds, and :exc:`TimeoutErrror` is raised if it
expires before a reply arrives.
:param msggen: A message generator object
:param ~blocking.DBusConnection connection: Connection to send and receive messages
:param float timeout: Default seconds to wait for a reply, or None for no limit
"""
def __init__(self, msggen, connection, *, timeout=None):
super().__init__(msggen)
self._connection = connection
self._timeout = timeout
def __repr__(self):
extra = '' if (self._timeout is None) else f', timeout={self._timeout}'
return f"Proxy({self._msggen}, {self._connection}{extra})"
def _method_call(self, make_msg):
@functools.wraps(make_msg)
def inner(*args, **kwargs):
timeout = kwargs.pop('_timeout', self._timeout)
msg = make_msg(*args, **kwargs)
assert msg.header.message_type is MessageType.method_call
return self._connection.send_and_get_reply(
msg, timeout=timeout, unwrap=True
)
return inner
def unwrap_read(b):
"""Raise ConnectionResetError from an empty read.
Sometimes the socket raises an error itself, sometimes it gives no data.
I haven't worked out when it behaves each way.
"""
if not b:
raise ConnectionResetError(ECONNRESET, os.strerror(ECONNRESET))
return b
def prep_socket(addr, enable_fds=False, timeout=2.0) -> socket.socket:
"""Create a socket and authenticate ready to send D-Bus messages"""
sock = socket.socket(family=socket.AF_UNIX)
# To impose the overall auth timeout, we'll update the timeout on the socket
# before each send/receive. This is ugly, but we can't use the socket for
# anything else until this has succeeded, so this should be safe.
deadline = timeout_to_deadline(timeout)
def with_sock_deadline(meth, *args):
sock.settimeout(deadline_to_timeout(deadline))
return meth(*args)
try:
with_sock_deadline(sock.connect, addr)
authr = Authenticator(enable_fds=enable_fds)
for req_data in authr:
with_sock_deadline(sock.sendall, req_data)
authr.feed(unwrap_read(with_sock_deadline(sock.recv, 1024)))
with_sock_deadline(sock.sendall, BEGIN)
except socket.timeout as e:
sock.close()
raise TimeoutError(f"Did not authenticate in {timeout} seconds") from e
except:
sock.close()
raise
sock.settimeout(None) # Put the socket back in blocking mode
return sock
def open_dbus_connection(
bus='SESSION', enable_fds=False, auth_timeout=1.,
) -> DBusConnection:
"""Connect to a D-Bus message bus
Pass ``enable_fds=True`` to allow sending & receiving file descriptors.
An error will be raised if the bus does not allow this. For simplicity,
it's advisable to leave this disabled unless you need it.
D-Bus has an authentication step before sending or receiving messages.
This takes < 1 ms in normal operation, but there is a timeout so that client
code won't get stuck if the server doesn't reply. *auth_timeout* configures
this timeout in seconds.
"""
bus_addr = get_bus(bus)
sock = prep_socket(bus_addr, enable_fds, timeout=auth_timeout)
conn = DBusConnection(sock, enable_fds)
return conn
if __name__ == '__main__':
conn = open_dbus_connection()
print("Unique name:", conn.unique_name)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/io/common.py 0000644 0000000 0000000 00000005210 00000000000 013753 0 ustar 00 from contextlib import contextmanager
from itertools import count
from jeepney import HeaderFields, Message, MessageFlag, MessageType
class MessageFilters:
def __init__(self):
self.filters = {}
self.filter_ids = count()
def matches(self, message):
for handle in self.filters.values():
if handle.rule.matches(message):
yield handle
class FilterHandle:
def __init__(self, filters: MessageFilters, rule, queue):
self._filters = filters
self._filter_id = next(filters.filter_ids)
self.rule = rule
self.queue = queue
self._filters.filters[self._filter_id] = self
def close(self):
del self._filters.filters[self._filter_id]
def __enter__(self):
return self.queue
def __exit__(self, exc_type, exc_val, exc_tb):
self.close()
return False
class ReplyMatcher:
def __init__(self):
self._futures = {}
@contextmanager
def catch(self, serial, future):
"""Context manager to capture a reply for the given serial number"""
self._futures[serial] = future
try:
yield future
finally:
del self._futures[serial]
def dispatch(self, msg):
"""Dispatch an incoming message which may be a reply
Returns True if a task was waiting for it, otherwise False.
"""
rep_serial = msg.header.fields.get(HeaderFields.reply_serial, -1)
if rep_serial in self._futures:
self._futures[rep_serial].set_result(msg)
return True
else:
return False
def drop_all(self, exc: Exception = None):
"""Throw an error in any task still waiting for a reply"""
if exc is None:
exc = RouterClosed("D-Bus router closed before reply arrived")
futures, self._futures = self._futures, {}
for fut in futures.values():
fut.set_exception(exc)
class RouterClosed(Exception):
"""Raised in tasks waiting for a reply when the router is closed
This will also be raised if the receiver task crashes, so tasks are not
stuck waiting for a reply that can never come. The router object will not
be usable after this is raised.
"""
pass
def check_replyable(msg: Message):
"""Raise an error if we wouldn't expect a reply for msg"""
if msg.header.message_type != MessageType.method_call:
raise TypeError("Only method call messages have replies "
f"(not {msg.header.message_type})")
if MessageFlag.no_reply_expected & msg.header.flags:
raise ValueError("This message has the no_reply_expected flag set")
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1910295
jeepney-0.7.1/jeepney/io/tests/__init__.py 0000644 0000000 0000000 00000000000 00000000000 015354 0 ustar 00 ././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1920295
jeepney-0.7.1/jeepney/io/tests/conftest.py 0000644 0000000 0000000 00000005252 00000000000 015460 0 ustar 00 from tempfile import TemporaryFile
import threading
import pytest
from jeepney import (
DBusAddress, HeaderFields, message_bus, MessageType, new_error,
new_method_return,
)
from jeepney.io.threading import open_dbus_connection, DBusRouter, Proxy
@pytest.fixture()
def respond_with_fd():
name = "io.gitlab.takluyver.jeepney.tests.respond_with_fd"
addr = DBusAddress(bus_name=name, object_path='/')
with open_dbus_connection(bus='SESSION', enable_fds=True) as conn:
with DBusRouter(conn) as router:
status, = Proxy(message_bus, router).RequestName(name)
assert status == 1 # DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
def _reply_once():
while True:
msg = conn.receive()
if msg.header.message_type is MessageType.method_call:
if msg.header.fields[HeaderFields.member] == 'GetFD':
with TemporaryFile('w+') as tf:
tf.write('readme')
tf.seek(0)
rep = new_method_return(msg, 'h', (tf,))
conn.send(rep)
return
else:
conn.send(new_error(msg, 'NoMethod'))
reply_thread = threading.Thread(target=_reply_once, daemon=True)
reply_thread.start()
yield addr
reply_thread.join()
@pytest.fixture()
def read_from_fd():
name = "io.gitlab.takluyver.jeepney.tests.read_from_fd"
addr = DBusAddress(bus_name=name, object_path='/')
with open_dbus_connection(bus='SESSION', enable_fds=True) as conn:
with DBusRouter(conn) as router:
status, = Proxy(message_bus, router).RequestName(name)
assert status == 1 # DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
def _reply_once():
while True:
msg = conn.receive()
if msg.header.message_type is MessageType.method_call:
if msg.header.fields[HeaderFields.member] == 'ReadFD':
with msg.body[0].to_file('rb') as f:
f.seek(0)
b = f.read()
conn.send(new_method_return(msg, 'ay', (b,)))
return
else:
conn.send(new_error(msg, 'NoMethod'))
reply_thread = threading.Thread(target=_reply_once, daemon=True)
reply_thread.start()
yield addr
reply_thread.join()
@pytest.fixture()
def temp_file_and_contents():
data = b'abc123'
with TemporaryFile('w+b') as tf:
tf.write(data)
tf.flush()
tf.seek(0)
yield tf, data
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1627495310.1410055
jeepney-0.7.1/jeepney/io/tests/test_asyncio.py 0000644 0000000 0000000 00000005046 00000000000 016340 0 ustar 00 import asyncio
import async_timeout
import pytest
from jeepney import DBusAddress, new_method_call
from jeepney.bus_messages import message_bus, MatchRule
from jeepney.io.asyncio import (
open_dbus_connection, open_dbus_router, Proxy
)
from .utils import have_session_bus
pytestmark = [
pytest.mark.asyncio,
pytest.mark.skipif(
not have_session_bus, reason="Tests require DBus session bus"
),
]
bus_peer = DBusAddress(
bus_name='org.freedesktop.DBus',
object_path='/org/freedesktop/DBus',
interface='org.freedesktop.DBus.Peer'
)
@pytest.fixture()
async def connection():
async with (await open_dbus_connection(bus='SESSION')) as conn:
yield conn
async def test_connect(connection):
assert connection.unique_name.startswith(':')
@pytest.fixture()
async def router():
async with open_dbus_router(bus='SESSION') as router:
yield router
async def test_send_and_get_reply(router):
ping_call = new_method_call(bus_peer, 'Ping')
reply = await asyncio.wait_for(
router.send_and_get_reply(ping_call), timeout=5
)
assert reply.body == ()
async def test_proxy(router):
proxy = Proxy(message_bus, router)
name = "io.gitlab.takluyver.jeepney.examples.Server"
res = await proxy.RequestName(name)
assert res in {(1,), (2,)} # 1: got the name, 2: queued
has_owner, = await proxy.NameHasOwner(name)
assert has_owner is True
async def test_filter(router):
bus = Proxy(message_bus, router)
name = "io.gitlab.takluyver.jeepney.tests.asyncio_test_filter"
match_rule = MatchRule(
type="signal",
sender=message_bus.bus_name,
interface=message_bus.interface,
member="NameOwnerChanged",
path=message_bus.object_path,
)
match_rule.add_arg_condition(0, name)
# Ask the message bus to subscribe us to this signal
await bus.AddMatch(match_rule)
with router.filter(match_rule) as queue:
res, = await bus.RequestName(name)
assert res == 1 # 1: got the name
signal_msg = await asyncio.wait_for(queue.get(), timeout=2.0)
assert signal_msg.body == (name, '', router.unique_name)
async def test_recv_after_connect():
# Can't use here:
# 1. 'connection' fixture
# 2. asyncio.wait_for()
# If (1) and/or (2) is used, the error won't be triggered.
conn = await open_dbus_connection(bus='SESSION')
try:
with pytest.raises(asyncio.TimeoutError):
async with async_timeout.timeout(0):
await conn.receive()
finally:
await conn.close()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1920295
jeepney-0.7.1/jeepney/io/tests/test_blocking.py 0000644 0000000 0000000 00000005645 00000000000 016470 0 ustar 00 import pytest
from jeepney import new_method_call, MessageType, DBusAddress
from jeepney.bus_messages import message_bus, MatchRule
from jeepney.io.blocking import open_dbus_connection, Proxy
from .utils import have_session_bus
pytestmark = pytest.mark.skipif(
not have_session_bus, reason="Tests require DBus session bus"
)
@pytest.fixture
def session_conn():
with open_dbus_connection(bus='SESSION') as conn:
yield conn
def test_connect(session_conn):
assert session_conn.unique_name.startswith(':')
bus_peer = DBusAddress(
bus_name='org.freedesktop.DBus',
object_path='/org/freedesktop/DBus',
interface='org.freedesktop.DBus.Peer'
)
def test_send_and_get_reply(session_conn):
ping_call = new_method_call(bus_peer, 'Ping')
reply = session_conn.send_and_get_reply(ping_call, timeout=5, unwrap=False)
assert reply.header.message_type == MessageType.method_return
assert reply.body == ()
ping_call = new_method_call(bus_peer, 'Ping')
reply_body = session_conn.send_and_get_reply(ping_call, timeout=5, unwrap=True)
assert reply_body == ()
def test_proxy(session_conn):
proxy = Proxy(message_bus, session_conn, timeout=5)
name = "io.gitlab.takluyver.jeepney.examples.Server"
res = proxy.RequestName(name)
assert res in {(1,), (2,)} # 1: got the name, 2: queued
has_owner, = proxy.NameHasOwner(name, _timeout=3)
assert has_owner is True
def test_filter(session_conn):
bus = Proxy(message_bus, session_conn)
name = "io.gitlab.takluyver.jeepney.tests.blocking_test_filter"
match_rule = MatchRule(
type="signal",
sender=message_bus.bus_name,
interface=message_bus.interface,
member="NameOwnerChanged",
path=message_bus.object_path,
)
match_rule.add_arg_condition(0, name)
# Ask the message bus to subscribe us to this signal
bus.AddMatch(match_rule)
with session_conn.filter(match_rule) as matches:
res, = bus.RequestName(name)
assert res == 1 # 1: got the name
signal_msg = session_conn.recv_until_filtered(matches, timeout=2)
assert signal_msg.body == (name, '', session_conn.unique_name)
def test_recv_fd(respond_with_fd):
getfd_call = new_method_call(respond_with_fd, 'GetFD')
with open_dbus_connection(bus='SESSION', enable_fds=True) as conn:
reply = conn.send_and_get_reply(getfd_call, timeout=5)
assert reply.header.message_type is MessageType.method_return
with reply.body[0].to_file('w+') as f:
assert f.read() == 'readme'
def test_send_fd(temp_file_and_contents, read_from_fd):
temp_file, data = temp_file_and_contents
readfd_call = new_method_call(read_from_fd, 'ReadFD', 'h', (temp_file,))
with open_dbus_connection(bus='SESSION', enable_fds=True) as conn:
reply = conn.send_and_get_reply(readfd_call, timeout=5)
assert reply.header.message_type is MessageType.method_return
assert reply.body[0] == data
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1920295
jeepney-0.7.1/jeepney/io/tests/test_threading.py 0000644 0000000 0000000 00000005213 00000000000 016634 0 ustar 00 import pytest
from jeepney import new_method_call, MessageType, DBusAddress
from jeepney.bus_messages import message_bus, MatchRule
from jeepney.io.threading import open_dbus_router, Proxy
from .utils import have_session_bus
pytestmark = pytest.mark.skipif(
not have_session_bus, reason="Tests require DBus session bus"
)
@pytest.fixture
def router():
with open_dbus_router(bus='SESSION') as conn:
yield conn
def test_connect(router):
assert router.unique_name.startswith(':')
bus_peer = DBusAddress(
bus_name='org.freedesktop.DBus',
object_path='/org/freedesktop/DBus',
interface='org.freedesktop.DBus.Peer'
)
def test_send_and_get_reply(router):
ping_call = new_method_call(bus_peer, 'Ping')
reply = router.send_and_get_reply(ping_call, timeout=5)
assert reply.header.message_type == MessageType.method_return
assert reply.body == ()
def test_proxy(router):
proxy = Proxy(message_bus, router, timeout=5)
name = "io.gitlab.takluyver.jeepney.examples.Server"
res = proxy.RequestName(name)
assert res in {(1,), (2,)} # 1: got the name, 2: queued
has_owner, = proxy.NameHasOwner(name, _timeout=3)
assert has_owner is True
def test_filter(router):
bus = Proxy(message_bus, router)
name = "io.gitlab.takluyver.jeepney.tests.threading_test_filter"
match_rule = MatchRule(
type="signal",
sender=message_bus.bus_name,
interface=message_bus.interface,
member="NameOwnerChanged",
path=message_bus.object_path,
)
match_rule.add_arg_condition(0, name)
# Ask the message bus to subscribe us to this signal
bus.AddMatch(match_rule)
with router.filter(match_rule) as queue:
res, = bus.RequestName(name)
assert res == 1 # 1: got the name
signal_msg = queue.get(timeout=2.0)
assert signal_msg.body == (name, '', router.unique_name)
def test_recv_fd(respond_with_fd):
getfd_call = new_method_call(respond_with_fd, 'GetFD')
with open_dbus_router(bus='SESSION', enable_fds=True) as router:
reply = router.send_and_get_reply(getfd_call, timeout=5)
assert reply.header.message_type is MessageType.method_return
with reply.body[0].to_file('w+') as f:
assert f.read() == 'readme'
def test_send_fd(temp_file_and_contents, read_from_fd):
temp_file, data = temp_file_and_contents
readfd_call = new_method_call(read_from_fd, 'ReadFD', 'h', (temp_file,))
with open_dbus_router(bus='SESSION', enable_fds=True) as router:
reply = router.send_and_get_reply(readfd_call, timeout=5)
assert reply.header.message_type is MessageType.method_return
assert reply.body[0] == data
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1920295
jeepney-0.7.1/jeepney/io/tests/test_trio.py 0000644 0000000 0000000 00000007464 00000000000 015656 0 ustar 00 import trio
import pytest
from jeepney import DBusAddress, DBusErrorResponse, MessageType, new_method_call
from jeepney.bus_messages import message_bus, MatchRule
from jeepney.io.trio import (
open_dbus_connection, open_dbus_router, Proxy,
)
from .utils import have_session_bus
pytestmark = [
pytest.mark.trio,
pytest.mark.skipif(
not have_session_bus, reason="Tests require DBus session bus"
),
]
# Can't use any async fixtures here, because pytest-asyncio tries to handle
# all of them: https://github.com/pytest-dev/pytest-asyncio/issues/124
async def test_connect():
conn = await open_dbus_connection(bus='SESSION')
async with conn:
assert conn.unique_name.startswith(':')
bus_peer = DBusAddress(
bus_name='org.freedesktop.DBus',
object_path='/org/freedesktop/DBus',
interface='org.freedesktop.DBus.Peer'
)
async def test_send_and_get_reply():
ping_call = new_method_call(bus_peer, 'Ping')
async with open_dbus_router(bus='SESSION') as req:
with trio.fail_after(5):
reply = await req.send_and_get_reply(ping_call)
assert reply.header.message_type == MessageType.method_return
assert reply.body == ()
async def test_send_and_get_reply_error():
ping_call = new_method_call(bus_peer, 'Snart') # No such method
async with open_dbus_router(bus='SESSION') as req:
with trio.fail_after(5):
reply = await req.send_and_get_reply(ping_call)
assert reply.header.message_type == MessageType.error
async def test_proxy():
async with open_dbus_router(bus='SESSION') as req:
proxy = Proxy(message_bus, req)
name = "io.gitlab.takluyver.jeepney.examples.Server"
res = await proxy.RequestName(name)
assert res in {(1,), (2,)} # 1: got the name, 2: queued
has_owner, = await proxy.NameHasOwner(name)
assert has_owner is True
async def test_proxy_error():
async with open_dbus_router(bus='SESSION') as req:
proxy = Proxy(message_bus, req)
with pytest.raises(DBusErrorResponse):
await proxy.RequestName(":123") # Invalid name
async def test_filter():
name = "io.gitlab.takluyver.jeepney.tests.trio_test_filter"
async with open_dbus_router(bus='SESSION') as router:
bus = Proxy(message_bus, router)
match_rule = MatchRule(
type="signal",
sender=message_bus.bus_name,
interface=message_bus.interface,
member="NameOwnerChanged",
path=message_bus.object_path,
)
match_rule.add_arg_condition(0, name)
# Ask the message bus to subscribe us to this signal
await bus.AddMatch(match_rule)
async with router.filter(match_rule) as chan:
res, = await bus.RequestName(name)
assert res == 1 # 1: got the name
with trio.fail_after(2.0):
signal_msg = await chan.receive()
assert signal_msg.body == (name, '', router.unique_name)
async def test_recv_fd(respond_with_fd):
getfd_call = new_method_call(respond_with_fd, 'GetFD')
with trio.fail_after(5):
async with open_dbus_router(bus='SESSION', enable_fds=True) as router:
reply = await router.send_and_get_reply(getfd_call)
assert reply.header.message_type is MessageType.method_return
with reply.body[0].to_file('w+') as f:
assert f.read() == 'readme'
async def test_send_fd(temp_file_and_contents, read_from_fd):
temp_file, data = temp_file_and_contents
readfd_call = new_method_call(read_from_fd, 'ReadFD', 'h', (temp_file,))
with trio.fail_after(5):
async with open_dbus_router(bus='SESSION', enable_fds=True) as router:
reply = await router.send_and_get_reply(readfd_call)
assert reply.header.message_type is MessageType.method_return
assert reply.body[0] == data
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1920295
jeepney-0.7.1/jeepney/io/tests/utils.py 0000644 0000000 0000000 00000000117 00000000000 014766 0 ustar 00 import os
have_session_bus = bool(os.environ.get('DBUS_SESSION_BUS_ADDRESS'))
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1920295
jeepney-0.7.1/jeepney/io/threading.py 0000644 0000000 0000000 00000022257 00000000000 014442 0 ustar 00 """Synchronous IO wrappers with thread safety
"""
from concurrent.futures import Future
from contextlib import contextmanager
import functools
import os
from selectors import EVENT_READ
import socket
from queue import Queue, Full as QueueFull
from threading import Lock, Thread
from typing import Optional
from jeepney import Message, MessageType
from jeepney.bus import get_bus
from jeepney.bus_messages import message_bus
from jeepney.wrappers import ProxyBase, unwrap_msg
from .blocking import (
unwrap_read, prep_socket, DBusConnectionBase, timeout_to_deadline,
)
from .common import (
MessageFilters, FilterHandle, ReplyMatcher, RouterClosed, check_replyable,
)
__all__ = [
'open_dbus_connection',
'open_dbus_router',
'DBusConnection',
'DBusRouter',
'Proxy',
'ReceiveStopped',
]
class ReceiveStopped(Exception):
pass
class DBusConnection(DBusConnectionBase):
def __init__(self, sock: socket.socket, enable_fds=False):
super().__init__(sock, enable_fds=enable_fds)
self._stop_r, self._stop_w = os.pipe()
self.stop_key = self.selector.register(self._stop_r, EVENT_READ)
self.send_lock = Lock()
self.rcv_lock = Lock()
def send(self, message: Message, serial=None):
"""Serialise and send a :class:`~.Message` object"""
data, fds = self._serialise(message, serial)
with self.send_lock:
if fds:
self._send_with_fds(data, fds)
else:
self.sock.sendall(data)
def receive(self, *, timeout=None) -> Message:
"""Return the next available message from the connection
If the data is ready, this will return immediately, even if timeout<=0.
Otherwise, it will wait for up to timeout seconds, or indefinitely if
timeout is None. If no message comes in time, it raises TimeoutError.
If the connection is closed from another thread, this will raise
ReceiveStopped.
"""
deadline = timeout_to_deadline(timeout)
if not self.rcv_lock.acquire(timeout=(timeout or -1)):
raise TimeoutError(f"Did not get receive lock in {timeout} seconds")
try:
return self._receive(deadline)
finally:
self.rcv_lock.release()
def _read_some_data(self, timeout=None):
# Wait for data or a signal on the stop pipe
for key, ev in self.selector.select(timeout):
if key == self.select_key:
if self.enable_fds:
return self._read_with_fds()
else:
return unwrap_read(self.sock.recv(4096)), []
elif key == self.stop_key:
raise ReceiveStopped("DBus receive stopped from another thread")
raise TimeoutError
def interrupt(self):
"""Make any threads waiting for a message raise ReceiveStopped"""
os.write(self._stop_w, b'a')
def reset_interrupt(self):
"""Allow calls to .receive() again after .interrupt()
To avoid race conditions, you should typically wait for threads to
respond (e.g. by joining them) between interrupting and resetting.
"""
# Clear any data on the stop pipe
while (self.stop_key, EVENT_READ) in self.selector.select(timeout=0):
os.read(self._stop_r, 1024)
def close(self):
"""Close the connection"""
self.interrupt()
super().close()
def open_dbus_connection(bus='SESSION', enable_fds=False, auth_timeout=1.):
"""Open a plain D-Bus connection
D-Bus has an authentication step before sending or receiving messages.
This takes < 1 ms in normal operation, but there is a timeout so that client
code won't get stuck if the server doesn't reply. *auth_timeout* configures
this timeout in seconds.
:return: :class:`DBusConnection`
"""
bus_addr = get_bus(bus)
sock = prep_socket(bus_addr, enable_fds, timeout=auth_timeout)
conn = DBusConnection(sock, enable_fds)
with DBusRouter(conn) as router:
reply_body = Proxy(message_bus, router, timeout=10).Hello()
conn.unique_name = reply_body[0]
return conn
class DBusRouter:
"""A client D-Bus connection which can wait for replies.
This runs a separate receiver thread and dispatches received messages.
It's possible to wrap a :class:`DBusConnection` in a router temporarily.
Using the connection directly while it is wrapped is not supported,
but you can use it again after the router is closed.
"""
def __init__(self, conn: DBusConnection):
self.conn = conn
self._replies = ReplyMatcher()
self._filters = MessageFilters()
self._rcv_thread = Thread(target=self._receiver, daemon=True)
self._rcv_thread.start()
@property
def unique_name(self):
return self.conn.unique_name
def send(self, message, *, serial=None):
"""Serialise and send a :class:`~.Message` object"""
self.conn.send(message, serial=serial)
def send_and_get_reply(self, msg: Message, *, timeout=None) -> Message:
"""Send a method call message, wait for and return a reply"""
check_replyable(msg)
if not self._rcv_thread.is_alive():
raise RouterClosed("This D-Bus router has stopped")
serial = next(self.conn.outgoing_serial)
with self._replies.catch(serial, Future()) as reply_fut:
self.conn.send(msg, serial=serial)
return reply_fut.result(timeout=timeout)
def close(self):
"""Close this router
This does not close the underlying connection.
"""
self.conn.interrupt()
self._rcv_thread.join(timeout=10)
self.conn.reset_interrupt()
def __enter__(self):
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.close()
return False
def filter(self, rule, *, queue: Optional[Queue] =None, bufsize=1):
"""Create a filter for incoming messages
Usage::
with router.filter(rule) as queue:
matching_msg = queue.get()
:param jeepney.MatchRule rule: Catch messages matching this rule
:param queue.Queue queue: Matched messages will be added to this
:param int bufsize: If no queue is passed in, create one with this size
"""
return FilterHandle(self._filters, rule, queue or Queue(maxsize=bufsize))
# Code to run in receiver thread ------------------------------------
def _dispatch(self, msg: Message):
if self._replies.dispatch(msg):
return
for filter in self._filters.matches(msg):
try:
filter.queue.put_nowait(msg)
except QueueFull:
pass
def _receiver(self):
try:
while True:
msg = self.conn.receive()
self._dispatch(msg)
except ReceiveStopped:
pass
finally:
# Send errors to any tasks still waiting for a message.
self._replies.drop_all()
class Proxy(ProxyBase):
"""A blocking proxy for calling D-Bus methods via a :class:`DBusRouter`.
You can call methods on the proxy object, such as ``bus_proxy.Hello()``
to make a method call over D-Bus and wait for a reply. It will either
return a tuple of returned data, or raise :exc:`.DBusErrorResponse`.
The methods available are defined by the message generator you wrap.
You can set a time limit on a call by passing ``_timeout=`` in the method
call, or set a default when creating the proxy. The ``_timeout`` argument
is not passed to the message generator.
All timeouts are in seconds, and :exc:`TimeoutErrror` is raised if it
expires before a reply arrives.
:param msggen: A message generator object
:param ~threading.DBusRouter router: Router to send and receive messages
:param float timeout: Default seconds to wait for a reply, or None for no limit
"""
def __init__(self, msggen, router, *, timeout=None):
super().__init__(msggen)
self._router = router
self._timeout = timeout
def __repr__(self):
extra = '' if (self._timeout is None) else f', timeout={self._timeout}'
return f"Proxy({self._msggen}, {self._router}{extra})"
def _method_call(self, make_msg):
@functools.wraps(make_msg)
def inner(*args, **kwargs):
timeout = kwargs.pop('_timeout', self._timeout)
msg = make_msg(*args, **kwargs)
assert msg.header.message_type is MessageType.method_call
reply = self._router.send_and_get_reply(msg, timeout=timeout)
return unwrap_msg(reply)
return inner
@contextmanager
def open_dbus_router(bus='SESSION', enable_fds=False):
"""Open a D-Bus 'router' to send and receive messages.
Use as a context manager::
with open_dbus_router() as router:
...
On leaving the ``with`` block, the connection will be closed.
:param str bus: 'SESSION' or 'SYSTEM' or a supported address.
:param bool enable_fds: Whether to enable passing file descriptors.
:return: :class:`DBusRouter`
"""
with open_dbus_connection(bus=bus, enable_fds=enable_fds) as conn:
with DBusRouter(conn) as router:
yield router
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1930296
jeepney-0.7.1/jeepney/io/tornado.py 0000644 0000000 0000000 00000015312 00000000000 014135 0 ustar 00 from asyncio import as_completed, Future, wait_for
from itertools import count
import socket
from typing import Optional
from warnings import warn
from tornado.ioloop import IOLoop
from tornado.iostream import IOStream
from tornado.locks import Event
from tornado.queues import Queue, QueueFull
from jeepney.auth import SASLParser, make_auth_external, BEGIN, AuthenticationError
from jeepney.bus import get_bus
from jeepney.low_level import Parser, MessageType, Message, MessageFlag
from jeepney.wrappers import ProxyBase, unwrap_msg
from jeepney.routing import Router
from jeepney.bus_messages import message_bus
from .common import (
MessageFilters, FilterHandle, ReplyMatcher, RouterClosed, check_replyable,
)
warn("jeepney.io.tornado is deprecated. Tornado is now built on top of "
"asyncio, so please use jeepney.io.asyncio instead.", stacklevel=2)
class DBusConnection:
def __init__(self, stream: IOStream):
self.stream = stream
self.parser = Parser()
self.outgoing_serial = count(start=1)
self.unique_name = None
async def send(self, message: Message, *, serial=None):
if serial is None:
serial = next(self.outgoing_serial)
# .write() immediately adds all the data to a buffer, so no lock needed
await self.stream.write(message.serialise(serial))
async def receive(self) -> Message:
while True:
msg = self.parser.get_next_message()
if msg is not None:
return msg
b = await self.stream.read_bytes(4096, partial=True)
self.parser.add_data(b)
def close(self):
self.stream.close()
async def open_dbus_connection(bus='SESSION'):
bus_addr = get_bus(bus)
stream = IOStream(socket.socket(family=socket.AF_UNIX))
await stream.connect(bus_addr)
await stream.write(b'\0' + make_auth_external())
auth_parser = SASLParser()
while not auth_parser.authenticated:
auth_parser.feed(await stream.read_bytes(1024, partial=True))
if auth_parser.error:
raise AuthenticationError(auth_parser.error)
await stream.write(BEGIN)
conn = DBusConnection(stream)
with DBusRouter(conn) as router:
reply_body = await wait_for(Proxy(message_bus, router).Hello(), 10)
conn.unique_name = reply_body[0]
return conn
class DBusRouter:
def __init__(self, conn: DBusConnection):
self.conn = conn
self._replies = ReplyMatcher()
self._filters = MessageFilters()
self._stop_receiving = Event()
IOLoop.current().add_callback(self._receiver)
# For backwards compatibility - old-style signal callbacks
self.router = Router(Future)
async def send(self, message, *, serial=None):
await self.conn.send(message, serial=serial)
async def send_and_get_reply(self, message):
check_replyable(message)
if self._stop_receiving.is_set():
raise RouterClosed("This DBusRouter has stopped")
serial = next(self.conn.outgoing_serial)
with self._replies.catch(serial, Future()) as reply_fut:
await self.send(message, serial=serial)
return (await reply_fut)
def filter(self, rule, *, queue: Optional[Queue] =None, bufsize=1):
"""Create a filter for incoming messages
Usage::
with router.filter(rule) as queue:
matching_msg = await queue.get()
:param jeepney.MatchRule rule: Catch messages matching this rule
:param tornado.queues.Queue queue: Matched messages will be added to this
:param int bufsize: If no queue is passed in, create one with this size
"""
return FilterHandle(self._filters, rule, queue or Queue(bufsize))
def stop(self):
self._stop_receiving.set()
def __enter__(self):
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.stop()
return False
# Backwards compatible interface (from old DBusConnection) --------
@property
def unique_name(self):
return self.conn.unique_name
async def send_message(self, message: Message):
if (
message.header.message_type == MessageType.method_return
and not (message.header.flags & MessageFlag.no_reply_expected)
):
return unwrap_msg(await self.send_and_get_reply(message))
else:
await self.send(message)
# Code to run in receiver task ------------------------------------
def _dispatch(self, msg: Message):
"""Handle one received message"""
if self._replies.dispatch(msg):
return
for filter in self._filters.matches(msg):
try:
filter.queue.put_nowait(msg)
except QueueFull:
pass
async def _receiver(self):
"""Receiver loop - runs in a separate task"""
try:
while True:
for coro in as_completed([self.conn.receive(), self._stop_receiving.wait()]):
msg = await coro
if msg is None:
return # Stopped
self._dispatch(msg)
self.router.incoming(msg)
finally:
self.is_running = False
# Send errors to any tasks still waiting for a message.
self._replies.drop_all()
class Proxy(ProxyBase):
def __init__(self, msggen, router: DBusRouter):
super().__init__(msggen)
self._router = router
def __repr__(self):
return 'Proxy({}, {})'.format(self._msggen, self._router)
def _method_call(self, make_msg):
async def inner(*args, **kwargs):
msg = make_msg(*args, **kwargs)
assert msg.header.message_type is MessageType.method_call
return unwrap_msg(await self._router.send_and_get_reply(msg))
return inner
class _RouterContext:
conn = None
router = None
def __init__(self, bus='SESSION'):
self.bus = bus
async def __aenter__(self):
self.conn = await open_dbus_connection(self.bus)
self.router = DBusRouter(self.conn)
return self.router
async def __aexit__(self, exc_type, exc_val, exc_tb):
self.router.stop()
self.conn.close()
def open_dbus_router(bus='SESSION'):
"""Open a D-Bus 'router' to send and receive messages.
Use as an async context manager::
async with open_dbus_router() as req:
...
:param str bus: 'SESSION' or 'SYSTEM' or a supported address.
:return: :class:`DBusRouter`
This is a shortcut for::
conn = await open_dbus_connection()
async with conn:
async with conn.router() as req:
...
"""
return _RouterContext(bus)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1930296
jeepney-0.7.1/jeepney/io/trio.py 0000644 0000000 0000000 00000035000 00000000000 013440 0 ustar 00 import array
from contextlib import contextmanager
import errno
from itertools import count
import logging
from typing import Optional
try:
from contextlib import asynccontextmanager # Python 3.7
except ImportError:
from async_generator import asynccontextmanager # Backport for Python 3.6
from outcome import Value, Error
import trio
from trio.abc import Channel
from jeepney.auth import Authenticator, BEGIN
from jeepney.bus import get_bus
from jeepney.fds import FileDescriptor, fds_buf_size
from jeepney.low_level import Parser, MessageType, Message
from jeepney.wrappers import ProxyBase, unwrap_msg
from jeepney.bus_messages import message_bus
from .common import (
MessageFilters, FilterHandle, ReplyMatcher, RouterClosed, check_replyable,
)
log = logging.getLogger(__name__)
__all__ = [
'open_dbus_connection',
'open_dbus_router',
'Proxy',
]
# The function below is copied from trio, which is under the MIT license:
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
@contextmanager
def _translate_socket_errors_to_stream_errors():
try:
yield
except OSError as exc:
if exc.errno in {errno.EBADF, errno.ENOTSOCK}:
# EBADF on Unix, ENOTSOCK on Windows
raise trio.ClosedResourceError("this socket was already closed") from None
else:
raise trio.BrokenResourceError(
"socket connection broken: {}".format(exc)
) from exc
class DBusConnection(Channel):
"""A plain D-Bus connection with no matching of replies.
This doesn't run any separate tasks: sending and receiving are done in
the task that calls those methods. It's suitable for implementing servers:
several worker tasks can receive requests and send replies.
For a typical client pattern, see :class:`DBusRouter`.
Implements trio's channel interface for Message objects.
"""
def __init__(self, socket, enable_fds=False):
self.socket = socket
self.enable_fds = enable_fds
self.parser = Parser()
self.outgoing_serial = count(start=1)
self.unique_name = None
self.send_lock = trio.Lock()
self.recv_lock = trio.Lock()
self._leftover_to_send = None # type: Optional[memoryview]
async def send(self, message: Message, *, serial=None):
"""Serialise and send a :class:`~.Message` object"""
async with self.send_lock:
if serial is None:
serial = next(self.outgoing_serial)
fds = array.array('i') if self.enable_fds else None
data = message.serialise(serial, fds=fds)
await self._send_data(data, fds)
# _send_data is copied & modified from trio's SocketStream.send_all() .
# See above for the MIT license.
async def _send_data(self, data: bytes, fds):
if self.socket.did_shutdown_SHUT_WR:
raise trio.ClosedResourceError("can't send data after sending EOF")
with _translate_socket_errors_to_stream_errors():
if self._leftover_to_send:
# A previous message was partly sent - finish sending it now.
await self._send_remainder(self._leftover_to_send)
with memoryview(data) as data:
if fds:
sent = await self.socket.sendmsg([data], [(
trio.socket.SOL_SOCKET, trio.socket.SCM_RIGHTS, fds
)])
else:
sent = await self.socket.send(data)
await self._send_remainder(data, sent)
async def _send_remainder(self, data: memoryview, already_sent=0):
try:
while already_sent < len(data):
with data[already_sent:] as remaining:
sent = await self.socket.send(remaining)
already_sent += sent
self._leftover_to_send = None
except trio.Cancelled:
# Sending cancelled mid-message. Keep track of the remaining data
# so it can be sent before the next message, otherwise the next
# message won't be recognised.
self._leftover_to_send = data[already_sent:]
raise
async def receive(self) -> Message:
"""Return the next available message from the connection"""
async with self.recv_lock:
while True:
msg = self.parser.get_next_message()
if msg is not None:
return msg
# Once data is read, it must be given to the parser with no
# checkpoints (where the task could be cancelled).
b, fds = await self._read_data()
if not b:
raise trio.EndOfChannel("Socket closed at the other end")
self.parser.add_data(b, fds)
async def _read_data(self):
if self.enable_fds:
nbytes = self.parser.bytes_desired()
with _translate_socket_errors_to_stream_errors():
data, ancdata, flags, _ = await self.socket.recvmsg(
nbytes, fds_buf_size()
)
if flags & getattr(trio.socket, 'MSG_CTRUNC', 0):
self._close()
raise RuntimeError("Unable to receive all file descriptors")
return data, FileDescriptor.from_ancdata(ancdata)
else: # not self.enable_fds
with _translate_socket_errors_to_stream_errors():
data = await self.socket.recv(4096)
return data, []
def _close(self):
self.socket.close()
self._leftover_to_send = None
# Our closing is currently sync, but AsyncResource objects must have aclose
async def aclose(self):
"""Close the D-Bus connection"""
self._close()
@asynccontextmanager
async def router(self):
"""Temporarily wrap this connection as a :class:`DBusRouter`
To be used like::
async with conn.router() as req:
reply = await req.send_and_get_reply(msg)
While the router is running, you shouldn't use :meth:`receive`.
Once the router is closed, you can use the plain connection again.
"""
async with trio.open_nursery() as nursery:
router = DBusRouter(self)
await router.start(nursery)
try:
yield router
finally:
await router.aclose()
async def open_dbus_connection(bus='SESSION', *, enable_fds=False) -> DBusConnection:
"""Open a plain D-Bus connection
:return: :class:`DBusConnection`
"""
bus_addr = get_bus(bus)
sock : trio.SocketStream = await trio.open_unix_socket(bus_addr)
# Authentication
authr = Authenticator(enable_fds=enable_fds)
for req_data in authr:
await sock.send_all(req_data)
authr.feed(await sock.receive_some())
await sock.send_all(BEGIN)
conn = DBusConnection(sock.socket, enable_fds=enable_fds)
# Say *Hello* to the message bus - this must be the first message, and the
# reply gives us our unique name.
async with conn.router() as router:
reply = await router.send_and_get_reply(message_bus.Hello())
conn.unique_name = reply.body[0]
return conn
class TrioFilterHandle(FilterHandle):
def __init__(self, filters: MessageFilters, rule, send_chn, recv_chn):
super().__init__(filters, rule, recv_chn)
self.send_channel = send_chn
@property
def receive_channel(self):
return self.queue
async def aclose(self):
self.close()
await self.send_channel.aclose()
async def __aenter__(self):
return self.queue
async def __aexit__(self, exc_type, exc_val, exc_tb):
await self.aclose()
class Future:
"""A very simple Future for trio based on `trio.Event`."""
def __init__(self):
self._outcome = None
self._event = trio.Event()
def set_result(self, result):
self._outcome = Value(result)
self._event.set()
def set_exception(self, exc):
self._outcome = Error(exc)
self._event.set()
async def get(self):
await self._event.wait()
return self._outcome.unwrap()
class DBusRouter:
"""A client D-Bus connection which can wait for replies.
This runs a separate receiver task and dispatches received messages.
"""
_nursery_mgr = None
_rcv_cancel_scope = None
def __init__(self, conn: DBusConnection):
self._conn = conn
self._replies = ReplyMatcher()
self._filters = MessageFilters()
@property
def unique_name(self):
return self._conn.unique_name
async def send(self, message, *, serial=None):
"""Send a message, don't wait for a reply
"""
await self._conn.send(message, serial=serial)
async def send_and_get_reply(self, message) -> Message:
"""Send a method call message and wait for the reply
Returns the reply message (method return or error message type).
"""
check_replyable(message)
if self._rcv_cancel_scope is None:
raise RouterClosed("This DBusRouter has stopped")
serial = next(self._conn.outgoing_serial)
with self._replies.catch(serial, Future()) as reply_fut:
await self.send(message, serial=serial)
return (await reply_fut.get())
def filter(self, rule, *, channel: Optional[trio.MemorySendChannel]=None, bufsize=1):
"""Create a filter for incoming messages
Usage::
async with router.filter(rule) as receive_channel:
matching_msg = await receive_channel.receive()
# OR:
send_chan, recv_chan = trio.open_memory_channel(1)
async with router.filter(rule, channel=send_chan):
matching_msg = await recv_chan.receive()
If the channel fills up,
The sending end of the channel is closed when leaving the ``async with``
block, whether or not it was passed in.
:param jeepney.MatchRule rule: Catch messages matching this rule
:param trio.MemorySendChannel channel: Send matching messages here
:param int bufsize: If no channel is passed in, create one with this size
"""
if channel is None:
channel, recv_channel = trio.open_memory_channel(bufsize)
else:
recv_channel = None
return TrioFilterHandle(self._filters, rule, channel, recv_channel)
# Task management -------------------------------------------
async def start(self, nursery: trio.Nursery):
if self._rcv_cancel_scope is not None:
raise RuntimeError("DBusRouter receiver task is already running")
self._rcv_cancel_scope = await nursery.start(self._receiver)
async def aclose(self):
"""Stop the sender & receiver tasks"""
# It doesn't matter if we receive a partial message - the connection
# should ensure that whatever is received is fed to the parser.
if self._rcv_cancel_scope is not None:
self._rcv_cancel_scope.cancel()
self._rcv_cancel_scope = None
# Ensure trio checkpoint
await trio.sleep(0)
# Code to run in receiver task ------------------------------------
def _dispatch(self, msg: Message):
"""Handle one received message"""
if self._replies.dispatch(msg):
return
for filter in self._filters.matches(msg):
try:
filter.send_channel.send_nowait(msg)
except trio.WouldBlock:
pass
async def _receiver(self, task_status=trio.TASK_STATUS_IGNORED):
"""Receiver loop - runs in a separate task"""
with trio.CancelScope() as cscope:
self.is_running = True
task_status.started(cscope)
try:
while True:
msg = await self._conn.receive()
self._dispatch(msg)
finally:
self.is_running = False
# Send errors to any tasks still waiting for a message.
self._replies.drop_all()
# Closing a memory channel can't block, but it only has an
# async close method, so we need to shield it from cancellation.
with trio.move_on_after(3) as cleanup_scope:
for filter in self._filters.filters.values():
cleanup_scope.shield = True
await filter.send_channel.aclose()
class Proxy(ProxyBase):
"""A trio proxy for calling D-Bus methods
You can call methods on the proxy object, such as ``await bus_proxy.Hello()``
to make a method call over D-Bus and wait for a reply. It will either
return a tuple of returned data, or raise :exc:`.DBusErrorResponse`.
The methods available are defined by the message generator you wrap.
:param msggen: A message generator object.
:param ~trio.DBusRouter router: Router to send and receive messages.
"""
def __init__(self, msggen, router):
super().__init__(msggen)
if not isinstance(router, DBusRouter):
raise TypeError("Proxy can only be used with DBusRequester")
self._router = router
def _method_call(self, make_msg):
async def inner(*args, **kwargs):
msg = make_msg(*args, **kwargs)
assert msg.header.message_type is MessageType.method_call
reply = await self._router.send_and_get_reply(msg)
return unwrap_msg(reply)
return inner
@asynccontextmanager
async def open_dbus_router(bus='SESSION', *, enable_fds=False):
"""Open a D-Bus 'router' to send and receive messages.
Use as an async context manager::
async with open_dbus_router() as req:
...
:param str bus: 'SESSION' or 'SYSTEM' or a supported address.
:return: :class:`DBusRouter`
This is a shortcut for::
conn = await open_dbus_connection()
async with conn:
async with conn.router() as req:
...
"""
conn = await open_dbus_connection(bus, enable_fds=enable_fds)
async with conn:
async with conn.router() as rtr:
yield rtr
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1930296
jeepney-0.7.1/jeepney/low_level.py 0000644 0000000 0000000 00000045257 00000000000 014063 0 ustar 00 from collections import deque
from enum import Enum, IntEnum, IntFlag
import struct
from typing import Optional
class SizeLimitError(ValueError):
"""Raised when trying to (de-)serialise data exceeding D-Bus' size limit.
This is currently only implemented for arrays, where the maximum size is
64 MiB.
"""
pass
class Endianness(Enum):
little = 1
big = 2
def struct_code(self):
return '<' if (self is Endianness.little) else '>'
def dbus_code(self):
return b'l' if (self is Endianness.little) else b'B'
endian_map = {b'l': Endianness.little, b'B': Endianness.big}
class MessageType(Enum):
method_call = 1
method_return = 2
error = 3
signal = 4
class MessageFlag(IntFlag):
no_reply_expected = 1
no_auto_start = 2
allow_interactive_authorization = 4
class HeaderFields(IntEnum):
path = 1
interface = 2
member = 3
error_name = 4
reply_serial = 5
destination = 6
sender = 7
signature = 8
unix_fds = 9
def padding(pos, step):
pad = step - (pos % step)
if pad == step:
return 0
return pad
class FixedType:
def __init__(self, size, struct_code):
self.size = self.alignment = size
self.struct_code = struct_code
def parse_data(self, buf, pos, endianness, fds=()):
pos += padding(pos, self.alignment)
code = endianness.struct_code() + self.struct_code
val = struct.unpack(code, buf[pos:pos + self.size])[0]
return val, pos + self.size
def serialise(self, data, pos, endianness, fds=None):
pad = b'\0' * padding(pos, self.alignment)
code = endianness.struct_code() + self.struct_code
return pad + struct.pack(code, data)
def __repr__(self):
return 'FixedType({!r}, {!r})'.format(self.size, self.struct_code)
def __eq__(self, other):
return (type(other) is FixedType) and (self.size == other.size) \
and (self.struct_code == other.struct_code)
class Boolean(FixedType):
def __init__(self):
super().__init__(4, 'I') # D-Bus booleans take 4 bytes
def parse_data(self, buf, pos, endianness, fds=()):
val, new_pos = super().parse_data(buf, pos, endianness)
return bool(val), new_pos
def __repr__(self):
return 'Boolean()'
def __eq__(self, other):
return type(other) is Boolean
class FileDescriptor(FixedType):
def __init__(self):
super().__init__(4, 'I')
def parse_data(self, buf, pos, endianness, fds=()):
idx, new_pos = super().parse_data(buf, pos, endianness)
return fds[idx], new_pos
def serialise(self, data, pos, endianness, fds=None):
if fds is None:
raise RuntimeError("Sending FDs is not supported or not enabled")
if hasattr(data, 'fileno'):
data = data.fileno()
if isinstance(data, bool) or not isinstance(data, int):
raise TypeError("Cannot use {data!r} as file descriptor. Expected "
"an int or an object with fileno() method")
if data < 0:
raise ValueError(f"File descriptor can't be negative ({data})")
fds.append(data)
return super().serialise(len(fds) - 1, pos, endianness)
def __repr__(self):
return 'FileDescriptor()'
def __eq__(self, other):
return type(other) is FileDescriptor
simple_types = {
'y': FixedType(1, 'B'), # unsigned 8 bit
'n': FixedType(2, 'h'), # signed 16 bit
'q': FixedType(2, 'H'), # unsigned 16 bit
'b': Boolean(), # bool (32-bit)
'i': FixedType(4, 'i'), # signed 32-bit
'u': FixedType(4, 'I'), # unsigned 32-bit
'x': FixedType(8, 'q'), # signed 64-bit
't': FixedType(8, 'Q'), # unsigned 64-bit
'd': FixedType(8, 'd'), # double
'h': FileDescriptor(), # file descriptor (uint32 index in a separate list)
}
class StringType:
def __init__(self, length_type):
self.length_type = length_type
@property
def alignment(self):
return self.length_type.size
def parse_data(self, buf, pos, endianness, fds=()):
length, pos = self.length_type.parse_data(buf, pos, endianness)
end = pos + length
val = buf[pos:end].decode('utf-8')
assert buf[end:end + 1] == b'\0'
return val, end + 1
def serialise(self, data, pos, endianness, fds=None):
if not isinstance(data, str):
raise TypeError("Expected str, not {!r}".format(data))
encoded = data.encode('utf-8')
len_data = self.length_type.serialise(len(encoded), pos, endianness)
return len_data + encoded + b'\0'
def __repr__(self):
return 'StringType({!r})'.format(self.length_type)
def __eq__(self, other):
return (type(other) is StringType) \
and (self.length_type == other.length_type)
simple_types.update({
's': StringType(simple_types['u']), # String
'o': StringType(simple_types['u']), # Object path
'g': StringType(simple_types['y']), # Signature
})
class Struct:
alignment = 8
def __init__(self, fields):
if any(isinstance(f, DictEntry) for f in fields):
raise TypeError("Found dict entry outside array")
self.fields = fields
def parse_data(self, buf, pos, endianness, fds=()):
pos += padding(pos, 8)
res = []
for field in self.fields:
v, pos = field.parse_data(buf, pos, endianness, fds=fds)
res.append(v)
return tuple(res), pos
def serialise(self, data, pos, endianness, fds=None):
if not isinstance(data, tuple):
raise TypeError("Expected tuple, not {!r}".format(data))
if len(data) != len(self.fields):
raise ValueError("{} entries for {} fields".format(
len(data), len(self.fields)
))
pad = b'\0' * padding(pos, self.alignment)
pos += len(pad)
res_pieces = []
for item, field in zip(data, self.fields):
res_pieces.append(field.serialise(item, pos, endianness, fds=fds))
pos += len(res_pieces[-1])
return pad + b''.join(res_pieces)
def __repr__(self):
return "{}({!r})".format(type(self).__name__, self.fields)
def __eq__(self, other):
return (type(other) is type(self)) and (self.fields == other.fields)
class DictEntry(Struct):
def __init__(self, fields):
if len(fields) != 2:
raise TypeError(
"Dict entry must have 2 fields, not %d" % len(fields))
if not isinstance(fields[0], (FixedType, StringType)):
raise TypeError(
"First field in dict entry must be simple type, not {}"
.format(type(fields[0])))
super().__init__(fields)
class Array:
alignment = 4
length_type = FixedType(4, 'I')
def __init__(self, elt_type):
self.elt_type = elt_type
def parse_data(self, buf, pos, endianness, fds=()):
# print('Array start', pos)
length, pos = self.length_type.parse_data(buf, pos, endianness)
pos += padding(pos, self.elt_type.alignment)
end = pos + length
if self.elt_type == simple_types['y']: # Array of bytes
return buf[pos:end], end
res = []
while pos < end:
# print('Array elem', pos)
v, pos = self.elt_type.parse_data(buf, pos, endianness, fds=fds)
res.append(v)
if isinstance(self.elt_type, DictEntry):
# Convert list of 2-tuples to dict
res = dict(res)
return res, pos
def serialise(self, data, pos, endianness, fds=None):
data_is_bytes = False
if isinstance(self.elt_type, DictEntry) and isinstance(data, dict):
data = data.items()
elif (self.elt_type == simple_types['y']) and isinstance(data, bytes):
data_is_bytes = True
elif not isinstance(data, list):
raise TypeError("Not suitable for array: {!r}".format(data))
# Fail fast if we know in advance that the data is too big:
if isinstance(self.elt_type, FixedType):
if (self.elt_type.size * len(data)) > 2**26:
raise SizeLimitError("Array size exceeds 64 MiB limit")
pad1 = padding(pos, self.alignment)
pos_after_length = pos + pad1 + 4
pad2 = padding(pos_after_length, self.elt_type.alignment)
if data_is_bytes:
buf = data
else:
data_pos = pos_after_length + pad2
limit_pos = data_pos + 2 ** 26
chunks = []
for item in data:
chunks.append(self.elt_type.serialise(
item, data_pos, endianness, fds=fds
))
data_pos += len(chunks[-1])
if data_pos > limit_pos:
raise SizeLimitError("Array size exceeds 64 MiB limit")
buf = b''.join(chunks)
len_data = self.length_type.serialise(len(buf), pos+pad1, endianness)
# print('Array ser: pad1={!r}, len_data={!r}, pad2={!r}, buf={!r}'.format(
# pad1, len_data, pad2, buf))
return (b'\0' * pad1) + len_data + (b'\0' * pad2) + buf
def __repr__(self):
return 'Array({!r})'.format(self.elt_type)
def __eq__(self, other):
return (type(other) is Array) and (self.elt_type == other.elt_type)
class Variant:
alignment = 1
def parse_data(self, buf, pos, endianness, fds=()):
# print('variant', pos)
sig, pos = simple_types['g'].parse_data(buf, pos, endianness)
# print('variant sig:', repr(sig), pos)
valtype = parse_signature(list(sig))
val, pos = valtype.parse_data(buf, pos, endianness, fds=fds)
# print('variant done', (sig, val), pos)
return (sig, val), pos
def serialise(self, data, pos, endianness, fds=None):
sig, data = data
valtype = parse_signature(list(sig))
sig_buf = simple_types['g'].serialise(sig, pos, endianness)
return sig_buf + valtype.serialise(
data, pos + len(sig_buf), endianness, fds=fds
)
def __repr__(self):
return 'Variant()'
def __eq__(self, other):
return type(other) is Variant
def parse_signature(sig):
"""Parse a symbolic signature into objects.
"""
# Based on http://norvig.com/lispy.html
token = sig.pop(0)
if token == 'a':
return Array(parse_signature(sig))
if token == 'v':
return Variant()
elif token == '(':
fields = []
while sig[0] != ')':
fields.append(parse_signature(sig))
sig.pop(0) # )
return Struct(fields)
elif token == '{':
de = []
while sig[0] != '}':
de.append(parse_signature(sig))
sig.pop(0) # }
return DictEntry(de)
elif token in ')}':
raise ValueError('Unexpected end of struct')
else:
return simple_types[token]
def calc_msg_size(buf):
endian, = struct.unpack('c', buf[:1])
endian = endian_map[endian]
body_length, = struct.unpack(endian.struct_code() + 'I', buf[4:8])
fields_array_len, = struct.unpack(endian.struct_code() + 'I', buf[12:16])
header_len = 16 + fields_array_len
return header_len + padding(header_len, 8) + body_length
_header_fields_type = Array(Struct([simple_types['y'], Variant()]))
def parse_header_fields(buf, endianness):
l, pos = _header_fields_type.parse_data(buf, 12, endianness)
return {HeaderFields(k): v[1] for (k, v) in l}, pos
header_field_codes = {
1: 'o',
2: 's',
3: 's',
4: 's',
5: 'u',
6: 's',
7: 's',
8: 'g',
9: 'u',
}
def serialise_header_fields(d, endianness):
l = [(i.value, (header_field_codes[i], v)) for (i, v) in sorted(d.items())]
return _header_fields_type.serialise(l, 12, endianness)
class Header:
def __init__(self, endianness, message_type, flags, protocol_version,
body_length, serial, fields):
"""A D-Bus message header
It's not normally necessary to construct this directly: use higher level
functions and methods instead.
"""
self.endianness = endianness
self.message_type = MessageType(message_type)
self.flags = MessageFlag(flags)
self.protocol_version = protocol_version
self.body_length = body_length
self.serial = serial
self.fields = fields
def __repr__(self):
return 'Header({!r}, {!r}, {!r}, {!r}, {!r}, {!r}, fields={!r})'.format(
self.endianness, self.message_type, self.flags,
self.protocol_version, self.body_length, self.serial, self.fields)
def serialise(self, serial=None):
s = self.endianness.struct_code() + 'cBBBII'
if serial is None:
serial = self.serial
return struct.pack(s, self.endianness.dbus_code(),
self.message_type.value, self.flags,
self.protocol_version,
self.body_length, serial) \
+ serialise_header_fields(self.fields, self.endianness)
@classmethod
def from_buffer(cls, buf):
endian, msgtype, flags, pv = struct.unpack('cBBB', buf[:4])
endian = endian_map[endian]
bodylen, serial = struct.unpack(endian.struct_code() + 'II', buf[4:12])
fields, pos = parse_header_fields(buf, endian)
return cls(endian, msgtype, flags, pv, bodylen, serial, fields), pos
class Message:
"""Object representing a DBus message.
It's not normally necessary to construct this directly: use higher level
functions and methods instead.
"""
def __init__(self, header, body):
self.header = header
self.body = body
def __repr__(self):
return "{}({!r}, {!r})".format(type(self).__name__, self.header, self.body)
@classmethod
def from_buffer(cls, buf: bytes, fds=()) -> 'Message':
header, pos = Header.from_buffer(buf)
n_fds = header.fields.get(HeaderFields.unix_fds, 0)
if n_fds > len(fds):
raise ValueError(
f"Message expects {n_fds} FDs, but only {len(fds)} were received"
)
fds = fds[:n_fds]
body = ()
if HeaderFields.signature in header.fields:
sig = header.fields[HeaderFields.signature]
body_type = parse_signature(list('(%s)' % sig))
body = body_type.parse_data(buf, pos, header.endianness, fds=fds)[0]
return Message(header, body)
def serialise(self, serial=None, fds=None) -> bytes:
"""Convert this message to bytes.
Specifying *serial* overrides the ``msg.header.serial`` field, so a
connection can use its own serial number without modifying the message.
If file-descriptor support is in use, *fds* should be a
:class:`array.array` object with type ``'i'``. Any file descriptors in
the message will be added to the array. If the message contains FDs,
it can't be serialised without this array.
"""
endian = self.header.endianness
if HeaderFields.signature in self.header.fields:
sig = self.header.fields[HeaderFields.signature]
body_type = parse_signature(list('(%s)' % sig))
body_buf = body_type.serialise(self.body, 0, endian, fds=fds)
else:
body_buf = b''
self.header.body_length = len(body_buf)
if fds:
self.header.fields[HeaderFields.unix_fds] = len(fds)
header_buf = self.header.serialise(serial=serial)
pad = b'\0' * padding(len(header_buf), 8)
return header_buf + pad + body_buf
class Parser:
"""Parse DBus messages from a stream of incoming data.
"""
def __init__(self):
self.buf = BufferPipe()
self.fds = []
self.next_msg_size = None
def add_data(self, data: bytes, fds=()):
"""Provide newly received data to the parser"""
self.buf.write(data)
self.fds.extend(fds)
def feed(self, data):
"""Feed the parser newly read data.
Returns a list of messages completed by the new data.
"""
self.add_data(data)
return list(iter(self.get_next_message, None))
def bytes_desired(self):
"""How many bytes can be received without going beyond the next message?
This is only used with file-descriptor passing, so we don't get too many
FDs in a single recvmsg call.
"""
got = self.buf.bytes_buffered
if got < 16: # The first 16 bytes tell us the message size
return 16 - got
if self.next_msg_size is None:
self.next_msg_size = calc_msg_size(self.buf.peek(16))
return self.next_msg_size - got
def get_next_message(self) -> Optional[Message]:
"""Parse one message, if there is enough data.
Returns None if it doesn't have a complete message.
"""
if self.next_msg_size is None:
if self.buf.bytes_buffered >= 16:
self.next_msg_size = calc_msg_size(self.buf.peek(16))
nms = self.next_msg_size
if (nms is not None) and self.buf.bytes_buffered >= nms:
raw_msg = self.buf.read(nms)
msg = Message.from_buffer(raw_msg, fds=self.fds)
self.next_msg_size = None
fds_consumed = msg.header.fields.get(HeaderFields.unix_fds, 0)
self.fds = self.fds[fds_consumed:]
return msg
class BufferPipe:
"""A place to store received data until we can parse a complete message
The main difference from io.BytesIO is that read & write operate at
opposite ends, like a pipe.
"""
def __init__(self):
self.chunks = deque()
self.bytes_buffered = 0
def write(self, b: bytes):
self.chunks.append(b)
self.bytes_buffered += len(b)
def _peek_iter(self, nbytes: int):
assert nbytes <= self.bytes_buffered
for chunk in self.chunks:
chunk = chunk[:nbytes]
nbytes -= len(chunk)
yield chunk
if nbytes <= 0:
break
def peek(self, nbytes: int) -> bytes:
"""Get exactly nbytes bytes from the front without removing them"""
return b''.join(self._peek_iter(nbytes))
def _read_iter(self, nbytes: int):
assert nbytes <= self.bytes_buffered
while True:
chunk = self.chunks.popleft()
self.bytes_buffered -= len(chunk)
if nbytes <= len(chunk):
break
nbytes -= len(chunk)
yield chunk
# Final chunk
chunk, rem = chunk[:nbytes], chunk[nbytes:]
if rem:
self.chunks.appendleft(rem)
self.bytes_buffered += len(rem)
yield chunk
def read(self, nbytes: int) -> bytes:
"""Take & return exactly nbytes bytes from the front"""
return b''.join(self._read_iter(nbytes))
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930899.7640395
jeepney-0.7.1/jeepney/routing.py 0000644 0000000 0000000 00000005413 00000000000 013550 0 ustar 00 from warnings import warn
from .low_level import MessageType, HeaderFields
from .wrappers import DBusErrorResponse
class Router:
"""Routing for messages coming back to a client application.
:param handle_factory: Constructor for an object like asyncio.Future,
with methods *set_result* and *set_exception*. Outgoing method call
messages will get a handle associated with them.
:param on_unhandled: Callback for messages not otherwise dispatched.
"""
def __init__(self, handle_factory, on_unhandled=None):
self.handle_factory = handle_factory
self._on_unhandled = on_unhandled
self.outgoing_serial = 0
self.awaiting_reply = {}
self.signal_callbacks = {}
@property
def on_unhandled(self):
return self._on_unhandled
@on_unhandled.setter
def on_unhandled(self, value):
warn("Setting on_unhandled is deprecated. Please use the filter() "
"method or simple receive() calls instead.", stacklevel=2)
self._on_unhandled = value
def outgoing(self, msg):
"""Set the serial number in the message & make a handle if a method call
"""
self.outgoing_serial += 1
msg.header.serial = self.outgoing_serial
if msg.header.message_type is MessageType.method_call:
self.awaiting_reply[msg.header.serial] = handle = self.handle_factory()
return handle
def subscribe_signal(self, callback, path, interface, member):
"""Add a callback for a signal.
"""
warn("The subscribe_signal() method is deprecated. "
"Please use the filter() API instead.", stacklevel=2)
self.signal_callbacks[(path, interface, member)] = callback
def incoming(self, msg):
"""Route an incoming message.
"""
hdr = msg.header
# Signals:
if hdr.message_type is MessageType.signal:
key = (hdr.fields.get(HeaderFields.path, None),
hdr.fields.get(HeaderFields.interface, None),
hdr.fields.get(HeaderFields.member, None)
)
cb = self.signal_callbacks.get(key, None)
if cb is not None:
cb(msg.body)
return
# Method returns & errors
reply_serial = hdr.fields.get(HeaderFields.reply_serial, -1)
reply_handle = self.awaiting_reply.pop(reply_serial, None)
if reply_handle is not None:
if hdr.message_type is MessageType.method_return:
reply_handle.set_result(msg.body)
return
elif hdr.message_type is MessageType.error:
reply_handle.set_exception(DBusErrorResponse(msg))
return
if self.on_unhandled:
self.on_unhandled(msg)
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1488048345.574467
jeepney-0.7.1/jeepney/tests/__init__.py 0000644 0000000 0000000 00000000000 00000000000 014745 0 ustar 00 ././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1496063709.491891
jeepney-0.7.1/jeepney/tests/secrets_introspect.xml 0000644 0000000 0000000 00000010737 00000000000 017322 0 ustar 00
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1940296
jeepney-0.7.1/jeepney/tests/test_auth.py 0000644 0000000 0000000 00000001143 00000000000 015217 0 ustar 00 import pytest
from jeepney import auth
def test_make_auth_external():
b = auth.make_auth_external()
assert b.startswith(b'AUTH EXTERNAL')
def test_make_auth_anonymous():
b = auth.make_auth_anonymous()
assert b.startswith(b'AUTH ANONYMOUS')
def test_parser():
p = auth.SASLParser()
p.feed(b'OK 728d62bc2eb394')
assert not p.authenticated
p.feed(b'1ebbb0b42958b1e0d6\r\n')
assert p.authenticated
def test_parser_rejected():
p = auth.SASLParser()
with pytest.raises(auth.AuthenticationError):
p.feed(b'REJECTED EXTERNAL\r\n')
assert not p.authenticated
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1496064311.983457
jeepney-0.7.1/jeepney/tests/test_bindgen.py 0000644 0000000 0000000 00000002112 00000000000 015661 0 ustar 00 from io import StringIO
import os.path
from jeepney.low_level import MessageType, HeaderFields
from jeepney.bindgen import code_from_xml
sample_file = os.path.join(os.path.dirname(__file__), 'secrets_introspect.xml')
def test_bindgen():
with open(sample_file) as f:
xml = f.read()
sio = StringIO()
n_interfaces = code_from_xml(xml, path='/org/freedesktop/secrets',
bus_name='org.freedesktop.secrets',
fh=sio)
# 5 interfaces defined, but we ignore Properties, Introspectable, Peer
assert n_interfaces == 2
# Run the generated code, defining the message generator classes.
binding_ns = {}
exec(sio.getvalue(), binding_ns)
Service = binding_ns['Service']
# Check basic functionality of the Service class
assert Service.interface == 'org.freedesktop.Secret.Service'
msg = Service().SearchItems({"service": "foo", "user": "bar"})
assert msg.header.message_type is MessageType.method_call
assert msg.header.fields[HeaderFields.destination] == 'org.freedesktop.secrets'
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1488127671.360318
jeepney-0.7.1/jeepney/tests/test_bus.py 0000644 0000000 0000000 00000001517 00000000000 015054 0 ustar 00 import pytest
from testpath import modified_env
from jeepney import bus
def test_get_connectable_addresses():
a = list(bus.get_connectable_addresses('unix:path=/run/user/1000/bus'))
assert a == ['/run/user/1000/bus']
a = list(bus.get_connectable_addresses('unix:abstract=/tmp/foo'))
assert a == ['\0/tmp/foo']
with pytest.raises(RuntimeError):
list(bus.get_connectable_addresses('unix:tmpdir=/tmp'))
def test_get_bus():
with modified_env({
'DBUS_SESSION_BUS_ADDRESS':'unix:path=/run/user/1000/bus',
'DBUS_SYSTEM_BUS_ADDRESS': 'unix:path=/var/run/dbus/system_bus_socket'
}):
assert bus.get_bus('SESSION') == '/run/user/1000/bus'
assert bus.get_bus('SYSTEM') == '/var/run/dbus/system_bus_socket'
assert bus.get_bus('unix:path=/run/user/1002/bus') == '/run/user/1002/bus'
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1940296
jeepney-0.7.1/jeepney/tests/test_bus_messages.py 0000644 0000000 0000000 00000006234 00000000000 016744 0 ustar 00 from jeepney import DBusAddress, new_signal, new_method_call
from jeepney.bus_messages import MatchRule, message_bus
portal = DBusAddress(
object_path='/org/freedesktop/portal/desktop',
bus_name='org.freedesktop.portal.Desktop',
)
portal_req_iface = portal.with_interface('org.freedesktop.portal.Request')
def test_match_rule_simple():
rule = MatchRule(
type='signal', interface='org.freedesktop.portal.Request',
)
assert rule.matches(new_signal(portal_req_iface, 'Response'))
# Wrong message type
assert not rule.matches(new_method_call(portal_req_iface, 'Boo'))
# Wrong interface
assert not rule.matches(new_signal(
portal.with_interface('org.freedesktop.portal.FileChooser'), 'Response'
))
def test_match_rule_path_namespace():
assert MatchRule(path_namespace='/org/freedesktop/portal').matches(
new_signal(portal_req_iface, 'Response')
)
# Prefix but not a parent in the path hierarchy
assert not MatchRule(path_namespace='/org/freedesktop/por').matches(
new_signal(portal_req_iface, 'Response')
)
def test_match_rule_arg():
rule = MatchRule(type='method_call')
rule.add_arg_condition(0, 'foo')
assert rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='s', body=('foo',)
))
assert not rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='s', body=('foobar',)
))
# No such argument
assert not rule.matches(new_method_call(portal_req_iface, 'Boo'))
def test_match_rule_arg_path():
rule = MatchRule(type='method_call')
rule.add_arg_condition(0, '/aa/bb/', kind='path')
# Exact match
assert rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='s', body=('/aa/bb/',)
))
# Match a prefix
assert rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='s', body=('/aa/bb/cc',)
))
# Argument is a prefix, ending with /
assert rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='s', body=('/aa/',)
))
# Argument is a prefix, but NOT ending with /
assert not rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='s', body=('/aa',)
))
assert not rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='s', body=('/aa/bb',)
))
# Not a string
assert not rule.matches(new_method_call(
portal_req_iface, 'Boo', signature='u', body=(12,)
))
def test_match_rule_arg_namespace():
rule = MatchRule(member='NameOwnerChanged')
rule.add_arg_condition(0, 'com.example.backend1', kind='namespace')
# Exact match
assert rule.matches(new_signal(
message_bus, 'NameOwnerChanged', 's', ('com.example.backend1',)
))
# Parent of the name
assert rule.matches(new_signal(
message_bus, 'NameOwnerChanged', 's', ('com.example.backend1.foo.bar',)
))
# Prefix but not a parent in the namespace
assert not rule.matches(new_signal(
message_bus, 'NameOwnerChanged', 's', ('com.example.backend12',)
))
# Not a string
assert not rule.matches(new_signal(
message_bus, 'NameOwnerChanged', 'u', (1,)
))
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1940296
jeepney-0.7.1/jeepney/tests/test_fds.py 0000644 0000000 0000000 00000003435 00000000000 015040 0 ustar 00 import errno
import os
import socket
import pytest
from jeepney import FileDescriptor, NoFDError
def assert_not_fd(fd: int):
"""Check that the given number is not open as a file descriptor"""
with pytest.raises(OSError) as exc_info:
os.stat(fd)
assert exc_info.value.errno == errno.EBADF
def test_close(tmp_path):
fd = os.open(tmp_path / 'a', os.O_CREAT | os.O_RDWR)
with FileDescriptor(fd) as wfd:
assert wfd.fileno() == fd
# Leaving the with block is equivalent to calling .close()
assert 'closed' in repr(wfd)
with pytest.raises(NoFDError):
wfd.fileno()
assert_not_fd(fd)
def test_to_raw_fd(tmp_path):
fd = os.open(tmp_path / 'a', os.O_CREAT)
wfd = FileDescriptor(fd)
assert wfd.fileno() == fd
assert wfd.to_raw_fd() == fd
try:
assert 'converted' in repr(wfd)
with pytest.raises(NoFDError):
wfd.fileno()
finally:
os.close(fd)
def test_to_file(tmp_path):
fd = os.open(tmp_path / 'a', os.O_CREAT | os.O_RDWR)
wfd = FileDescriptor(fd)
with wfd.to_file('w') as f:
assert f.write('abc')
assert 'converted' in repr(wfd)
with pytest.raises(NoFDError):
wfd.fileno()
assert_not_fd(fd) # Check FD was closed by file object
assert (tmp_path / 'a').read_text() == 'abc'
def test_to_socket():
s1, s2 = socket.socketpair()
try:
s1.sendall(b'abcd')
sfd = s2.detach()
wfd = FileDescriptor(sfd)
with wfd.to_socket() as sock:
b = sock.recv(16)
assert b and b'abcd'.startswith(b)
assert 'converted' in repr(wfd)
with pytest.raises(NoFDError):
wfd.fileno()
assert_not_fd(sfd) # Check FD was closed by socket object
finally:
s1.close()
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1536692852.036692
jeepney-0.7.1/jeepney/tests/test_low_level.py 0000644 0000000 0000000 00000004772 00000000000 016261 0 ustar 00 import pytest
from jeepney.low_level import *
HELLO_METHOD_CALL = (
b'l\x01\x00\x01\x00\x00\x00\x00\x01\x00\x00\x00m\x00\x00\x00\x01\x01o\x00\x15'
b'\x00\x00\x00/org/freedesktop/DBus\x00\x00\x00\x02\x01s\x00\x14\x00\x00\x00'
b'org.freedesktop.DBus\x00\x00\x00\x00\x03\x01s\x00\x05\x00\x00\x00Hello\x00'
b'\x00\x00\x06\x01s\x00\x14\x00\x00\x00org.freedesktop.DBus\x00\x00\x00\x00')
def test_parser_simple():
msg = Parser().feed(HELLO_METHOD_CALL)[0]
assert msg.header.fields[HeaderFields.member] == 'Hello'
def chunks(src, size):
pos = 0
while pos < len(src):
end = pos + size
yield src[pos:end]
pos = end
def test_parser_chunks():
p = Parser()
chunked = list(chunks(HELLO_METHOD_CALL, 16))
for c in chunked[:-1]:
assert p.feed(c) == []
msg = p.feed(chunked[-1])[0]
assert msg.header.fields[HeaderFields.member] == 'Hello'
def test_multiple():
msgs = Parser().feed(HELLO_METHOD_CALL * 6)
assert len(msgs) == 6
for msg in msgs:
assert msg.header.fields[HeaderFields.member] == 'Hello'
def test_roundtrip():
msg = Parser().feed(HELLO_METHOD_CALL)[0]
assert msg.serialise() == HELLO_METHOD_CALL
def test_serialise_dict():
data = {
'a': 'b',
'de': 'f',
}
string_type = simple_types['s']
sig = Array(DictEntry([string_type, string_type]))
print(sig.serialise(data, 0, Endianness.little))
assert sig.serialise(data, 0, Endianness.little) == (
b'\x1e\0\0\0' + # Length
b'\0\0\0\0' + # Padding
b'\x01\0\0\0a\0\0\0' +
b'\x01\0\0\0b\0\0\0' +
b'\x02\0\0\0de\0\0' +
b'\x01\0\0\0f\0'
)
def test_parse_signature():
sig = parse_signature(list('(a{sv}(oayays)b)'))
print(sig)
assert sig == Struct([
Array(DictEntry([simple_types['s'], Variant()])),
Struct([
simple_types['o'],
Array(simple_types['y']),
Array(simple_types['y']),
simple_types['s']
]),
simple_types['b'],
])
class fake_list(list):
def __init__(self, n):
super().__init__()
self._n = n
def __len__(self):
return self._n
def __iter__(self):
return iter(range(self._n))
def test_array_limit():
# The spec limits arrays to 64 MiB
a = Array(FixedType(8, 'Q')) # 'at' - array of uint64
a.serialise(fake_list(100), 0, Endianness.little)
with pytest.raises(SizeLimitError):
a.serialise(fake_list(2**23 + 1), 0, Endianness.little)
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 010211 x ustar 00 27 mtime=1496058352.322167
jeepney-0.7.1/jeepney/tests/test_routing.py 0000644 0000000 0000000 00000001677 00000000000 015761 0 ustar 00 from asyncio import Future
import pytest
from jeepney.routing import Router
from jeepney.wrappers import new_method_return, new_error, DBusErrorResponse
from jeepney.bus_messages import message_bus
def test_message_reply():
router = Router(Future)
call = message_bus.Hello()
future = router.outgoing(call)
router.incoming(new_method_return(call, 's', ('test',)))
assert future.result() == ('test',)
def test_error():
router = Router(Future)
call = message_bus.Hello()
future = router.outgoing(call)
router.incoming(new_error(call, 'TestError', 'u', (31,)))
with pytest.raises(DBusErrorResponse) as e:
future.result()
assert e.value.name == 'TestError'
assert e.value.data == (31,)
def test_unhandled():
unhandled = []
router = Router(Future, on_unhandled=unhandled.append)
msg = message_bus.Hello()
router.incoming(msg)
assert len(unhandled) == 1
assert unhandled[0] == msg
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1625930389.1940296
jeepney-0.7.1/jeepney/wrappers.py 0000644 0000000 0000000 00000017453 00000000000 013733 0 ustar 00 from typing import Union
from warnings import warn
from .low_level import *
__all__ = [
'DBusAddress',
'new_method_call',
'new_method_return',
'new_error',
'new_signal',
'MessageGenerator',
'Properties',
'Introspectable',
'DBusErrorResponse',
]
class DBusAddress:
"""This identifies the object and interface a message is for.
e.g. messages to display desktop notifications would have this address::
DBusAddress('/org/freedesktop/Notifications',
bus_name='org.freedesktop.Notifications',
interface='org.freedesktop.Notifications')
"""
def __init__(self, object_path, bus_name=None, interface=None):
self.object_path = object_path
self.bus_name = bus_name
self.interface = interface
def __repr__(self):
return '{}({!r}, bus_name={!r}, interface={!r})'.format(type(self).__name__,
self.object_path, self.bus_name, self.interface)
def with_interface(self, interface):
return type(self)(self.object_path, self.bus_name, interface)
class DBusObject(DBusAddress):
def __init__(self, object_path, bus_name=None, interface=None):
super().__init__(object_path, bus_name, interface)
warn('Deprecated alias, use DBusAddress instead', stacklevel=2)
def new_header(msg_type):
return Header(Endianness.little, msg_type, flags=0, protocol_version=1,
body_length=-1, serial=-1, fields={})
def new_method_call(remote_obj, method, signature=None, body=()):
"""Construct a new method call message
This is a relatively low-level method. In many cases, this will be called
from a :class:`MessageGenerator` subclass which provides a more convenient
API.
:param DBusAddress remote_obj: The object to call a method on
:param str method: The name of the method to call
:param str signature: The DBus signature of the body data
:param tuple body: Body data (i.e. method parameters)
"""
header = new_header(MessageType.method_call)
header.fields[HeaderFields.path] = remote_obj.object_path
if remote_obj.bus_name is None:
raise ValueError("remote_obj.bus_name cannot be None for method calls")
header.fields[HeaderFields.destination] = remote_obj.bus_name
if remote_obj.interface is not None:
header.fields[HeaderFields.interface] = remote_obj.interface
header.fields[HeaderFields.member] = method
if signature is not None:
header.fields[HeaderFields.signature] = signature
return Message(header, body)
def new_method_return(parent_msg, signature=None, body=()):
"""Construct a new response message
:param Message parent_msg: The method call this is a reply to
:param str signature: The DBus signature of the body data
:param tuple body: Body data
"""
header = new_header(MessageType.method_return)
header.fields[HeaderFields.reply_serial] = parent_msg.header.serial
sender = parent_msg.header.fields.get(HeaderFields.sender, None)
if sender is not None:
header.fields[HeaderFields.destination] = sender
if signature is not None:
header.fields[HeaderFields.signature] = signature
return Message(header, body)
def new_error(parent_msg, error_name, signature=None, body=()):
"""Construct a new error response message
:param Message parent_msg: The method call this is a reply to
:param str error_name: The name of the error
:param str signature: The DBus signature of the body data
:param tuple body: Body data
"""
header = new_header(MessageType.error)
header.fields[HeaderFields.reply_serial] = parent_msg.header.serial
header.fields[HeaderFields.error_name] = error_name
sender = parent_msg.header.fields.get(HeaderFields.sender, None)
if sender is not None:
header.fields[HeaderFields.destination] = sender
if signature is not None:
header.fields[HeaderFields.signature] = signature
return Message(header, body)
def new_signal(emitter, signal, signature=None, body=()):
"""Construct a new signal message
:param DBusAddress emitter: The object sending the signal
:param str signal: The name of the signal
:param str signature: The DBus signature of the body data
:param tuple body: Body data
"""
header = new_header(MessageType.signal)
header.fields[HeaderFields.path] = emitter.object_path
if emitter.interface is None:
raise ValueError("emitter.interface cannot be None for signals")
header.fields[HeaderFields.interface] = emitter.interface
header.fields[HeaderFields.member] = signal
if signature is not None:
header.fields[HeaderFields.signature] = signature
return Message(header, body)
class MessageGenerator:
"""Subclass this to define the methods available on a DBus interface.
jeepney.bindgen can automatically create subclasses using introspection.
"""
def __init__(self, object_path, bus_name):
self.object_path = object_path
self.bus_name = bus_name
def __repr__(self):
return "{}({!r}, bus_name={!r})".format(type(self).__name__,
self.object_path, self.bus_name)
class ProxyBase:
"""A proxy is an IO-aware wrapper around a MessageGenerator
Calling methods on a proxy object will send a message and wait for the
reply. This is a base class for proxy implementations in jeepney.io.
"""
def __init__(self, msggen):
self._msggen = msggen
def __getattr__(self, item):
if item.startswith('__'):
raise AttributeError(item)
make_msg = getattr(self._msggen, item, None)
if callable(make_msg):
return self._method_call(make_msg)
raise AttributeError(item)
def _method_call(self, make_msg):
raise NotImplementedError("Needs to be implemented in subclass")
class Properties:
"""Build messages for accessing object properties
If a D-Bus object has multiple interfaces, each interface has its own
set of properties.
This uses the standard DBus interface ``org.freedesktop.DBus.Properties``
"""
def __init__(self, obj: Union[DBusAddress, MessageGenerator]):
self.obj = obj
self.props_if = DBusAddress(obj.object_path, bus_name=obj.bus_name,
interface='org.freedesktop.DBus.Properties')
def get(self, name):
"""Get the value of the property *name*"""
return new_method_call(self.props_if, 'Get', 'ss',
(self.obj.interface, name))
def get_all(self):
"""Get all property values for this interface"""
return new_method_call(self.props_if, 'GetAll', 's',
(self.obj.interface,))
def set(self, name, signature, value):
"""Set the property *name* to *value* (with appropriate signature)"""
return new_method_call(self.props_if, 'Set', 'ssv',
(self.obj.interface, name, (signature, value)))
class Introspectable(MessageGenerator):
interface = 'org.freedesktop.DBus.Introspectable'
def Introspect(self):
"""Request D-Bus introspection XML for a remote object"""
return new_method_call(self, 'Introspect')
class DBusErrorResponse(Exception):
"""Raised by proxy method calls when the reply is an error message"""
def __init__(self, msg):
self.name = msg.header.fields.get(HeaderFields.error_name)
self.data = msg.body
def __str__(self):
return '[{}] {}'.format(self.name, self.data)
def unwrap_msg(msg: Message):
"""Get the body of a message, raising DBusErrorResponse for error messages
This is to be used with replies to method_call messages, which may be
method_return or error.
"""
if msg.header.message_type == MessageType.error:
raise DBusErrorResponse(msg)
return msg.body
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1627495310.1410055
jeepney-0.7.1/pyproject.toml 0000644 0000000 0000000 00000001357 00000000000 012767 0 ustar 00 [build-system]
requires = ["flit_core >=2,<4"]
build-backend = "flit_core.buildapi"
[tool.flit.metadata]
module = "jeepney"
author = "Thomas Kluyver"
author-email = "thomas@kluyver.me.uk"
home-page = "https://gitlab.com/takluyver/jeepney"
description-file = "README.rst"
requires-python = ">=3.6"
classifiers = [
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Topic :: Desktop Environment"
]
[tool.flit.metadata.requires-extra]
test = [
"pytest",
"pytest-trio",
"pytest-asyncio",
"testpath",
"trio",
"async-timeout",
]
trio = [
"trio",
"async_generator; python_version == '3.6'",
]
[tool.flit.metadata.urls]
Documentation = "https://jeepney.readthedocs.io/en/latest/"
jeepney-0.7.1/setup.py 0000644 0000000 0000000 00000001566 00000000000 011567 0 ustar 00 #!/usr/bin/env python
# setup.py generated by flit for tools that don't yet use PEP 517
from distutils.core import setup
packages = \
['jeepney',
'jeepney.integrate',
'jeepney.integrate.tests',
'jeepney.io',
'jeepney.io.tests',
'jeepney.tests']
package_data = \
{'': ['*']}
extras_require = \
{'test': ['pytest',
'pytest-trio',
'pytest-asyncio',
'testpath',
'trio',
'async-timeout'],
'trio': ['trio'],
"trio:python_version == '3.6'": ['async_generator']}
setup(name='jeepney',
version='0.7.1',
description='Low-level, pure Python DBus protocol wrapper.',
author='Thomas Kluyver',
author_email='thomas@kluyver.me.uk',
url='https://gitlab.com/takluyver/jeepney',
packages=packages,
package_data=package_data,
extras_require=extras_require,
python_requires='>=3.6',
)
jeepney-0.7.1/PKG-INFO 0000644 0000000 0000000 00000002371 00000000000 011145 0 ustar 00 Metadata-Version: 2.1
Name: jeepney
Version: 0.7.1
Summary: Low-level, pure Python DBus protocol wrapper.
Home-page: https://gitlab.com/takluyver/jeepney
Author: Thomas Kluyver
Author-email: thomas@kluyver.me.uk
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Desktop Environment
Requires-Dist: pytest ; extra == "test"
Requires-Dist: pytest-trio ; extra == "test"
Requires-Dist: pytest-asyncio ; extra == "test"
Requires-Dist: testpath ; extra == "test"
Requires-Dist: trio ; extra == "test"
Requires-Dist: async-timeout ; extra == "test"
Requires-Dist: trio ; extra == "trio"
Requires-Dist: async_generator ; extra == "trio" and ( python_version == '3.6')
Project-URL: Documentation, https://jeepney.readthedocs.io/en/latest/
Provides-Extra: test
Provides-Extra: trio
Jeepney is a pure Python implementation of D-Bus messaging. It has an `I/O-free
`__ core, and integration modules for different
event loops.
D-Bus is an inter-process communication system, mainly used in Linux.
To install Jeepney::
pip install jeepney
`Jeepney docs on Readthedocs `__