From fc2e6ad7b7b6f650210baafeca1aad120e1a94e3 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 00:09:39 +0200 Subject: [PATCH 1/8] docs: adjust comment about sys.path note that it is usually not needed to tweak sys.path, one just needs to have msgpack installed (like into a currently active venv) and it will be found. i adjusted the path in the comment nevertheless, so if somebody wants the stuff in docs/../msgpack to be found, it just needs to be uncommented. sys.path tweaking might also cause issues i guess, e.g. if docs/../msgpack is found first and stuff from there is tried, instead of a correctly installed msgpack somewhere else in sys.path. --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 91ce77f0..1c1895c7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,7 @@ # 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. -# sys.path.insert(0, os.path.abspath('.')) +#sys.path.insert(0, os.path.abspath('..')) # -- General configuration ----------------------------------------------------- From b14d743f04f510d135be85cb1a2bf3fb4ddbd29a Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 00:19:50 +0200 Subject: [PATCH 2/8] tox: add sphinx testenv --- tox.ini | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/tox.ini b/tox.ini index 1ef2d189..369eddcf 100644 --- a/tox.ini +++ b/tox.ini @@ -3,6 +3,7 @@ envlist = {py35,py36,py37,py38}-{c,pure}, {pypy,pypy3}-pure, py34-x86, + sphinx, isolated_build = true [testenv] @@ -27,3 +28,11 @@ commands= python -c 'import sys; print(hex(sys.maxsize))' python -c 'from msgpack import _cmsgpack' py.test + + +[testenv:sphinx] +changedir = docs +deps = + sphinx +commands = + sphinx-build -n -v -W --keep-going -b html -d {envtmpdir}/doctrees . {envtmpdir}/html From 479b6b5c38ab448c78934d668a3f5140ac53db2b Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 01:35:28 +0200 Subject: [PATCH 3/8] github: build the docs --- .github/workflows/docs.yaml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/workflows/docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..a393c6b8 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,32 @@ +name: docs + +on: ["push", "pull_request"] + +jobs: + docs: + # We want to run on external PRs, but not on our own internal PRs as they'll be run + # by the push to the branch. + if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository + + runs-on: ubuntu-latest + steps: + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.x' + architecture: 'x64' + + - name: Checkout + uses: actions/checkout@v3 + + - name: Build + shell: bash + run: | + pip install -r requirements.txt + make cython + pip install . + + - name: Sphinx Documentation Generator + run: | + pip install tox + tox -e sphinx From 74fb0f4a800b372abb2a31ae76e494d6d2041c40 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 01:45:25 +0200 Subject: [PATCH 4/8] sphinx: add docs/_static to avoid warning --- docs/_static/README.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/_static/README.txt diff --git a/docs/_static/README.txt b/docs/_static/README.txt new file mode 100644 index 00000000..1c70594f --- /dev/null +++ b/docs/_static/README.txt @@ -0,0 +1 @@ +Sphinx will copy the contents of docs/_static/ directory to the build location. From 85c272b276b8c2e0757623520ba85b0ceb1af904 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 00:35:17 +0200 Subject: [PATCH 5/8] fix sphinx warnings in ext.py --- msgpack/ext.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/msgpack/ext.py b/msgpack/ext.py index 97942949..f7f2d77d 100644 --- a/msgpack/ext.py +++ b/msgpack/ext.py @@ -120,7 +120,7 @@ def from_unix(unix_sec): """Create a Timestamp from posix timestamp in seconds. :param unix_float: Posix timestamp in seconds. - :type unix_float: int or float. + :type unix_float: int or float """ seconds = int(unix_sec // 1) nanoseconds = int((unix_sec % 1) * 10**9) @@ -154,7 +154,7 @@ def to_unix_nano(self): def to_datetime(self): """Get the timestamp as a UTC datetime. - :rtype: datetime. + :rtype: `datetime.datetime` """ utc = datetime.timezone.utc return datetime.datetime.fromtimestamp(0, utc) + datetime.timedelta(seconds=self.to_unix()) From 7a59dab0e67b85249a3823541515bbe81c37be6f Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 01:07:59 +0200 Subject: [PATCH 6/8] fix py:func reference target not found Fixes: WARNING: py:func reference target not found: dump WARNING: py:func reference target not found: dumps WARNING: py:func reference target not found: load WARNING: py:func reference target not found: loads --- docs/api.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 93827e19..f5dfbbd2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -5,19 +5,19 @@ API reference .. autofunction:: pack -:func:`dump` is alias for :func:`pack` +``dump()`` is an alias for :func:`pack` .. autofunction:: packb -:func:`dumps` is alias for :func:`packb` +``dumps()`` is an alias for :func:`packb` .. autofunction:: unpack -:func:`load` is alias for :func:`unpack` +``load()`` is an alias for :func:`unpack` .. autofunction:: unpackb -:func:`loads` is alias for :func:`unpackb` +``loads()`` is an alias for :func:`unpackb` .. autoclass:: Packer :members: From 487f889b1fb57f6eca5a138cca9826d2639eff23 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 01:58:47 +0200 Subject: [PATCH 7/8] fix py:meth reference target not found msgpack.fallback.Unpacker:6: WARNING: py:meth reference target not found: feed --- msgpack/_unpacker.pyx | 2 +- msgpack/fallback.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/msgpack/_unpacker.pyx b/msgpack/_unpacker.pyx index d5dc5ea5..ff29e2a7 100644 --- a/msgpack/_unpacker.pyx +++ b/msgpack/_unpacker.pyx @@ -217,7 +217,7 @@ cdef class Unpacker(object): :param file_like: File-like object having `.read(n)` method. - If specified, unpacker reads serialized data from it and :meth:`feed()` is not usable. + If specified, unpacker reads serialized data from it and `.feed()` is not usable. :param int read_size: Used as `file_like.read(read_size)`. (default: `min(16*1024, max_buffer_size)`) diff --git a/msgpack/fallback.py b/msgpack/fallback.py index ac1eaf4c..41199e86 100644 --- a/msgpack/fallback.py +++ b/msgpack/fallback.py @@ -139,7 +139,7 @@ class Unpacker: :param file_like: File-like object having `.read(n)` method. - If specified, unpacker reads serialized data from it and :meth:`feed()` is not usable. + If specified, unpacker reads serialized data from it and `.feed()` is not usable. :param int read_size: Used as `file_like.read(read_size)`. (default: `min(16*1024, max_buffer_size)`) From 1c4f7d1fae2857e07b596e30ab2522f4169ec5d7 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 26 Aug 2023 01:21:07 +0200 Subject: [PATCH 8/8] fix warnings related to callable type WARNING: py:class reference target not found: callable --- msgpack/_packer.pyx | 3 ++- msgpack/_unpacker.pyx | 4 ++-- msgpack/fallback.py | 7 ++++--- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/msgpack/_packer.pyx b/msgpack/_packer.pyx index 074b39fc..3c398672 100644 --- a/msgpack/_packer.pyx +++ b/msgpack/_packer.pyx @@ -71,7 +71,8 @@ cdef class Packer(object): Packer's constructor has some keyword arguments: - :param callable default: + :param default: + When specified, it should be callable. Convert user type to builtin type that Packer supports. See also simplejson's document. diff --git a/msgpack/_unpacker.pyx b/msgpack/_unpacker.pyx index ff29e2a7..56126f43 100644 --- a/msgpack/_unpacker.pyx +++ b/msgpack/_unpacker.pyx @@ -241,12 +241,12 @@ cdef class Unpacker(object): :param bool strict_map_key: If true (default), only str or bytes are accepted for map (dict) keys. - :param callable object_hook: + :param object_hook: When specified, it should be callable. Unpacker calls it with a dict argument after unpacking msgpack map. (See also simplejson) - :param callable object_pairs_hook: + :param object_pairs_hook: When specified, it should be callable. Unpacker calls it with a list of key-value pairs after unpacking msgpack map. (See also simplejson) diff --git a/msgpack/fallback.py b/msgpack/fallback.py index 41199e86..84b2617a 100644 --- a/msgpack/fallback.py +++ b/msgpack/fallback.py @@ -163,12 +163,12 @@ class Unpacker: :param bool strict_map_key: If true (default), only str or bytes are accepted for map (dict) keys. - :param callable object_hook: + :param object_hook: When specified, it should be callable. Unpacker calls it with a dict argument after unpacking msgpack map. (See also simplejson) - :param callable object_pairs_hook: + :param object_pairs_hook: When specified, it should be callable. Unpacker calls it with a list of key-value pairs after unpacking msgpack map. (See also simplejson) @@ -616,7 +616,8 @@ class Packer: Packer's constructor has some keyword arguments: - :param callable default: + :param default: + When specified, it should be callable. Convert user type to builtin type that Packer supports. See also simplejson's document.