| Name | gjson JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | https://github.com/volans-/gjson-py |
| Summary | gjson-py is a Python package that provides a simple way to filter and extract data from JSON-like objects or JSON files, using the GJSON syntax. |
| upload_time | 2023-01-24 11:58:48 |
| maintainer | |
| docs_url | None |
| author | Riccardo Coccioli |
| requires_python | >=3.9 |
| license | GPLv3+ |
| keywords |
gjson
json
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://github.com/volans-/gjson-py/actions/workflows/run-tox.yaml/badge.svg
:alt: CI results
:target: https://github.com/volans-/gjson-py/actions/workflows/run-tox.yaml
Introduction
============
gjson-py is a Python package that provides a simple way to filter and extract data from JSON-like objects or JSON
files, using the `GJSON`_ syntax.
It is, compatibly with the language differences and with some limitation, the Python equivalent of the Go
`GJSON`_ package.
The main difference from GJSON is that gjson-py doesn't work directly with JSON strings but instead with
JSON-like Python objects, that can either be the resulting object when calling ``json.load()`` or ``json.loads()``,
or any Python object that is JSON-serializable.
A detailed list of the GJSON features supported by gjson-py is provided below.
See also the full `gjson-py documentation`_.
Installation
------------
gjson-py is available on the `Python Package Index`_ (PyPI) and can be easily installed with::
pip install gjson
A ``debian`` branch is also present with all the configuration to build the package for Debian-based systems.
A ``.deb`` package for the current stable and unstable Debian versions is also available for download on the
`releases page on GitHub`_.
How to use the library
----------------------
gjson-py provides different ways to perform queries on JSON-like objects.
``gjson.get()``
^^^^^^^^^^^^^^^
A quick accessor to GJSON functionalities exposed for simplicity of use. Particularly useful to perform a single
query on a given object::
>>> import gjson
>>> data = {'name': {'first': 'Tom', 'last': 'Anderson'}, 'age': 37}
>>> gjson.get(data, 'name.first')
'Tom'
It's also possible to make it return a JSON-encoded string and decide on failure if it should raise an exception
or return `None`. See the full API documentation for more details.
``GJSON`` class
^^^^^^^^^^^^^^^
The ``GJSON`` class provides full access to the gjson-py API allowing to perform multiple queries on the same object::
>>> import gjson
>>> data = {'name': {'first': 'Tom', 'last': 'Anderson'}, 'age': 37}
>>> source = gjson.GJSON(data)
>>> source.get('name.first')
'Tom'
>>> str(source)
'{"name": {"first": "Tom", "last": "Anderson"}, "age": 37}'
>>> source.getj('name.first')
'"Tom"'
>>> name = source.get_gjson('name')
>>> name.get('first')
'Tom'
>>> name
<gjson.GJSON object at 0x102735b20>
See the full API documentation for more details.
How to use the CLI
------------------
gjson-py provides also a command line interface (CLI) for ease of use:
.. code-block:: console
$ echo '{"name": {"first": "Tom", "last": "Anderson"}, "age": 37}' > test.json
$ cat test.json | gjson 'name.first' # Read from stdin
"Tom"
$ gjson test.json 'age' # Read from a file
37
$ cat test.json | gjson - 'name.first' # Explicitely read from stdin
"Tom"
JSON Lines
^^^^^^^^^^
JSON Lines support in the CLI allows for different use cases. All the examples in this section operates on a
``test.json`` file generated with:
.. code-block:: console
$ echo -e '{"name": "Gilbert", "age": 61}\n{"name": "Alexa", "age": 34}\n{"name": "May", "age": 57}' > test.json
Apply the same query to each line
"""""""""""""""""""""""""""""""""
Using the ``-l/--lines`` CLI argument, for each input line gjson-py applies the query and filters the data according
to it. Lines are read one by one so there is no memory overhead for the processing. It can be used while tailing log
files in JSON format for example.
.. code-block:: console
$ gjson --lines test.json 'age'
61
34
57
$ tail -f log.json | gjson --lines 'bytes_sent' # Dummy example
Encapsulate all lines in an array, then apply the query
"""""""""""""""""""""""""""""""""""""""""""""""""""""""
Using the special query prefix syntax ``..``, as described in GJSON's documentation for `JSON Lines`_, gjson-py will
read all lines from the input and encapsulate them into an array. This approach has of course the memory overhead of
loading the whole input to perform the query.
.. code-block:: console
$ gjson test.json '..#.name'
["Gilbert", "Alexa", "May"]
Filter lines based on their values
""""""""""""""""""""""""""""""""""
Combining the ``-l/--lines`` CLI argument with the special query prefix ``..`` described above, it's possible to filter
input lines based on their values. In this case gjson-py encapsulates each line in an array so that is possible to use
the `Queries`_ GJSON syntax to filter them. As the ecapsulation is performed on each line, there is no memory overhead.
Because technically when a line is filtered is because there was no match on the whole line query, the final exit code,
if any line is filtered, will be ``1``.
.. code-block:: console
$ gjson --lines test.json '..#(age>40).name'
"Gilbert"
"May"
Filter lines and apply query to the result
""""""""""""""""""""""""""""""""""""""""""
Combining the methods above is possible for example to filter/extract data from the lines first and then apply a query
to the aggregated result. The memory overhead in this case is based on the amount of data resulting from the first
filtering/extraction.
.. code-block:: console
$ gjson --lines test.json 'age' | gjson '..@sort'
[34, 57, 61]
$ gjson --lines test.json '..#(age>40).age' | gjson '..@sort'
[57, 61]
Query syntax
------------
For the generic query syntax refer to the original `GJSON Path Syntax`_ documentation.
Supported GJSON features
^^^^^^^^^^^^^^^^^^^^^^^^
This is the list of GJSON features and how they are supported by gjson-py:
+------------------------+------------------------+------------------------------------------------------+
| GJSON feature | Supported by gjson-py | Notes |
+========================+========================+======================================================+
| `Path Structure`_ | YES | |
+------------------------+------------------------+------------------------------------------------------+
| `Basic`_ | YES | |
+------------------------+------------------------+------------------------------------------------------+
| `Wildcards`_ | YES | |
+------------------------+------------------------+------------------------------------------------------+
| `Escape Character`_ | YES | |
+------------------------+------------------------+------------------------------------------------------+
| `Arrays`_ | YES | |
+------------------------+------------------------+------------------------------------------------------+
| `Queries`_ | YES | Using Python's operators [#]_ [#]_ |
+------------------------+------------------------+------------------------------------------------------+
| `Dot vs Pipe`_ | YES | |
+------------------------+------------------------+------------------------------------------------------+
| `Modifiers`_ | YES | See the table below for all the details |
+------------------------+------------------------+------------------------------------------------------+
| `Modifier arguments`_ | YES | Only a JSON object is accepted as argument |
+------------------------+------------------------+------------------------------------------------------+
| `Custom modifiers`_ | YES | Only a JSON object is accepted as argument [#]_ |
+------------------------+------------------------+------------------------------------------------------+
| `Multipaths`_ | YES | Object keys, if specified, must be JSON strings [#]_ |
+------------------------+------------------------+------------------------------------------------------+
| `Literals`_ | YES | Including infinite and NaN values [#]_ |
+------------------------+------------------------+------------------------------------------------------+
| `JSON Lines`_ | YES | CLI support [#]_ [#]_ |
+------------------------+------------------------+------------------------------------------------------+
.. [#] The queries matching is based on Python's operator and as such the results might be different than the ones from
the Go GJSON package. In particular for the ``~`` operator that checks the truthy-ness of objects.
.. [#] When using nested queries, only the outermost one controls whether to return only the first item or all items.
.. [#] Custom modifiers names cannot contain reserved characters used by the GJSON grammar.
.. [#] For example ``{"years":age}`` is valid while ``{years:age}`` is not, although that's valid in GJSON.
.. [#] Those special cases are handled according to `Python's JSON documentation`_.
.. [#] Both for applying the same query to each line using the ``-l/--lines`` argument and to automatically encapsulate
the input lines in a list and apply the query to the list using the ``..`` special query prefix described in
`JSON Lines`_.
.. [#] Library support is not currently present because gjson-py accepts only Python objects, making it impossible to
pass JSON Lines directly. The client is free to choose if calling gjson-py for each line or to encapsulate them in
a list before calling gjson-py.
This is the list of modifiers present in GJSON and how they are supported by gjson-py:
+----------------+-----------------------+------------------------------------------+
| GJSON Modifier | Supported by gjson-py | Notes |
+----------------+-----------------------+------------------------------------------+
| ``@reverse`` | YES | |
+----------------+-----------------------+------------------------------------------+
| ``@ugly`` | YES | |
+----------------+-----------------------+------------------------------------------+
| ``@pretty`` | PARTIALLY | The ``width`` argument is not supported |
+----------------+-----------------------+------------------------------------------+
| ``@this`` | YES | |
+----------------+-----------------------+------------------------------------------+
| ``@valid`` | YES | |
+----------------+-----------------------+------------------------------------------+
| ``@flatten`` | YES | |
+----------------+-----------------------+------------------------------------------+
| ``@join`` | PARTIALLY | Preserving duplicate keys not supported |
+----------------+-----------------------+------------------------------------------+
| ``@keys`` | YES | Valid only on JSON objects (mappings) |
+----------------+-----------------------+------------------------------------------+
| ``@values`` | YES | Valid only on JSON objects (mappings) |
+----------------+-----------------------+------------------------------------------+
| ``@tostr`` | YES | |
+----------------+-----------------------+------------------------------------------+
| ``@fromstr`` | YES | |
+----------------+-----------------------+------------------------------------------+
| ``@group`` | YES | |
+----------------+-----------------------+------------------------------------------+
Additional features
^^^^^^^^^^^^^^^^^^^
Additional modifiers
""""""""""""""""""""
This is the list of additional modifiers specific to gjson-py not present in GJSON:
* ``@ascii``: escapes all non-ASCII characters when printing/returning the string representation of the object,
ensuring that the output is made only of ASCII characters. It's implemented using the ``ensure_ascii`` arguments in
the Python's ``json`` module. This modifier doesn't accept any arguments.
* ``@sort``: sorts a mapping object by its keys or a sequence object by its values. This modifier doesn't accept any
arguments.
* ``@top_n``: given a sequence object groups the items in the sequence counting how many occurrences of each value are
present. It returns a mapping object where the keys are the distinct values of the list and the values are the number
of times the key was present in the list, ordered from the most common to the least common item. The items in the
original sequence object must be Python hashable. This modifier accepts an optional argument ``n`` to return just the
N items with the higher counts. When the ``n`` argument is not provided all items are returned. Example usage:
.. code-block:: console
$ echo '["a", "b", "c", "b", "c", "c"]' | gjson '@top_n'
{"c": 3, "b": 2, "a": 1}
$ echo '["a", "b", "c", "b", "c", "c"]' | gjson '@top_n:{"n":2}'
{"c": 3, "b": 2}
* ``@sum_n``: given a sequence of objects, groups the items in the sequence using a grouping key and sum the values of a
sum key provided. It returns a mapping object where the keys are the distinct values of the grouping key and the
values are the sums of all the values of the sum key for each distinct grouped key, ordered from the highest sum to
the lowest. The values of the grouping key must be Python hashable. The values of the sum key must be integers or
floats. This modifier required two mandatory arguments, ``group`` and ``sum`` that have as values the respective keys
in the objects of the sequence. An optional ``n`` argument is also accepted to return just the top N items with the
highest sum. Example usage:
.. code-block:: console
$ echo '[{"key": "a", "time": 1}, {"key": "b", "time": 2}, {"key": "c", "time": 3}, {"key": "a", "time": 4}]' > test.json
$ gjson test.json '@sum_n:{"group": "key", "sum": "time"}'
{"a": 5, "c": 3, "b": 2}
$ gjson test.json '@sum_n:{"group": "key", "sum": "time", "n": 2}'
{"a": 5, "c": 3}
.. _`GJSON`: https://github.com/tidwall/gjson
.. _`Python Package Index`: https://pypi.org/project/gjson/
.. _`GJSON Path Syntax`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md
.. _`gjson-py documentation`: https://volans-.github.io/gjson-py/index.html
.. _`releases page on GitHub`: https://github.com/volans-/gjson-py/releases
.. _`Python's JSON documentation`: https://docs.python.org/3/library/json.html#infinite-and-nan-number-values
.. _`Path Structure`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#path-structure
.. _`Basic`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#basic
.. _`Wildcards`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#wildcards
.. _`Escape Character`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#escape-character
.. _`Arrays`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#arrays
.. _`Queries`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#queries
.. _`Dot vs Pipe`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#dot-vs-pipe
.. _`Modifiers`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#modifiers
.. _`Modifier arguments`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#modifiers
.. _`Custom modifiers`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#custom-modifiers
.. _`Multipaths`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#multipaths
.. _`Literals`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#literals
.. _`JSON Lines`: https://github.com/tidwall/gjson#json-lines
Raw data
{
"_id": null,
"home_page": "https://github.com/volans-/gjson-py",
"name": "gjson",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "gjson,json",
"author": "Riccardo Coccioli",
"author_email": "volans-@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/d7/7e/2d99200e3fa2a8a1b01230ed84c06a6fb15726fd1e070f1c32f7b0df2e9a/gjson-1.0.0.tar.gz",
"platform": "GNU/Linux",
"description": ".. image:: https://github.com/volans-/gjson-py/actions/workflows/run-tox.yaml/badge.svg\n :alt: CI results\n :target: https://github.com/volans-/gjson-py/actions/workflows/run-tox.yaml\n\nIntroduction\n============\n\ngjson-py is a Python package that provides a simple way to filter and extract data from JSON-like objects or JSON\nfiles, using the `GJSON`_ syntax.\n\nIt is, compatibly with the language differences and with some limitation, the Python equivalent of the Go\n`GJSON`_ package.\nThe main difference from GJSON is that gjson-py doesn't work directly with JSON strings but instead with\nJSON-like Python objects, that can either be the resulting object when calling ``json.load()`` or ``json.loads()``,\nor any Python object that is JSON-serializable.\n\nA detailed list of the GJSON features supported by gjson-py is provided below.\n\nSee also the full `gjson-py documentation`_.\n\nInstallation\n------------\n\ngjson-py is available on the `Python Package Index`_ (PyPI) and can be easily installed with::\n\n pip install gjson\n\nA ``debian`` branch is also present with all the configuration to build the package for Debian-based systems.\nA ``.deb`` package for the current stable and unstable Debian versions is also available for download on the\n`releases page on GitHub`_.\n\nHow to use the library\n----------------------\n\ngjson-py provides different ways to perform queries on JSON-like objects.\n\n``gjson.get()``\n^^^^^^^^^^^^^^^\n\nA quick accessor to GJSON functionalities exposed for simplicity of use. Particularly useful to perform a single\nquery on a given object::\n\n >>> import gjson\n >>> data = {'name': {'first': 'Tom', 'last': 'Anderson'}, 'age': 37}\n >>> gjson.get(data, 'name.first')\n 'Tom'\n\nIt's also possible to make it return a JSON-encoded string and decide on failure if it should raise an exception\nor return `None`. See the full API documentation for more details.\n\n``GJSON`` class\n^^^^^^^^^^^^^^^\n\nThe ``GJSON`` class provides full access to the gjson-py API allowing to perform multiple queries on the same object::\n\n >>> import gjson\n >>> data = {'name': {'first': 'Tom', 'last': 'Anderson'}, 'age': 37}\n >>> source = gjson.GJSON(data)\n >>> source.get('name.first')\n 'Tom'\n >>> str(source)\n '{\"name\": {\"first\": \"Tom\", \"last\": \"Anderson\"}, \"age\": 37}'\n >>> source.getj('name.first')\n '\"Tom\"'\n >>> name = source.get_gjson('name')\n >>> name.get('first')\n 'Tom'\n >>> name\n <gjson.GJSON object at 0x102735b20>\n\nSee the full API documentation for more details.\n\nHow to use the CLI\n------------------\n\ngjson-py provides also a command line interface (CLI) for ease of use:\n\n.. code-block:: console\n\n $ echo '{\"name\": {\"first\": \"Tom\", \"last\": \"Anderson\"}, \"age\": 37}' > test.json\n $ cat test.json | gjson 'name.first' # Read from stdin\n \"Tom\"\n $ gjson test.json 'age' # Read from a file\n 37\n $ cat test.json | gjson - 'name.first' # Explicitely read from stdin\n \"Tom\"\n\nJSON Lines\n^^^^^^^^^^\n\nJSON Lines support in the CLI allows for different use cases. All the examples in this section operates on a\n``test.json`` file generated with:\n\n.. code-block:: console\n\n $ echo -e '{\"name\": \"Gilbert\", \"age\": 61}\\n{\"name\": \"Alexa\", \"age\": 34}\\n{\"name\": \"May\", \"age\": 57}' > test.json\n\nApply the same query to each line\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nUsing the ``-l/--lines`` CLI argument, for each input line gjson-py applies the query and filters the data according\nto it. Lines are read one by one so there is no memory overhead for the processing. It can be used while tailing log\nfiles in JSON format for example.\n\n\n.. code-block:: console\n\n $ gjson --lines test.json 'age'\n 61\n 34\n 57\n $ tail -f log.json | gjson --lines 'bytes_sent' # Dummy example\n\nEncapsulate all lines in an array, then apply the query\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nUsing the special query prefix syntax ``..``, as described in GJSON's documentation for `JSON Lines`_, gjson-py will\nread all lines from the input and encapsulate them into an array. This approach has of course the memory overhead of\nloading the whole input to perform the query.\n\n.. code-block:: console\n\n $ gjson test.json '..#.name'\n [\"Gilbert\", \"Alexa\", \"May\"]\n\nFilter lines based on their values\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nCombining the ``-l/--lines`` CLI argument with the special query prefix ``..`` described above, it's possible to filter\ninput lines based on their values. In this case gjson-py encapsulates each line in an array so that is possible to use\nthe `Queries`_ GJSON syntax to filter them. As the ecapsulation is performed on each line, there is no memory overhead.\nBecause technically when a line is filtered is because there was no match on the whole line query, the final exit code,\nif any line is filtered, will be ``1``.\n\n.. code-block:: console\n\n $ gjson --lines test.json '..#(age>40).name'\n \"Gilbert\"\n \"May\"\n\nFilter lines and apply query to the result\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nCombining the methods above is possible for example to filter/extract data from the lines first and then apply a query\nto the aggregated result. The memory overhead in this case is based on the amount of data resulting from the first\nfiltering/extraction.\n\n.. code-block:: console\n\n $ gjson --lines test.json 'age' | gjson '..@sort'\n [34, 57, 61]\n $ gjson --lines test.json '..#(age>40).age' | gjson '..@sort'\n [57, 61]\n\nQuery syntax\n------------\n\nFor the generic query syntax refer to the original `GJSON Path Syntax`_ documentation.\n\nSupported GJSON features\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis is the list of GJSON features and how they are supported by gjson-py:\n\n\n+------------------------+------------------------+------------------------------------------------------+\n| GJSON feature | Supported by gjson-py | Notes |\n+========================+========================+======================================================+\n| `Path Structure`_ | YES | |\n+------------------------+------------------------+------------------------------------------------------+\n| `Basic`_ | YES | |\n+------------------------+------------------------+------------------------------------------------------+\n| `Wildcards`_ | YES | |\n+------------------------+------------------------+------------------------------------------------------+\n| `Escape Character`_ | YES | |\n+------------------------+------------------------+------------------------------------------------------+\n| `Arrays`_ | YES | |\n+------------------------+------------------------+------------------------------------------------------+\n| `Queries`_ | YES | Using Python's operators [#]_ [#]_ |\n+------------------------+------------------------+------------------------------------------------------+\n| `Dot vs Pipe`_ | YES | |\n+------------------------+------------------------+------------------------------------------------------+\n| `Modifiers`_ | YES | See the table below for all the details |\n+------------------------+------------------------+------------------------------------------------------+\n| `Modifier arguments`_ | YES | Only a JSON object is accepted as argument |\n+------------------------+------------------------+------------------------------------------------------+\n| `Custom modifiers`_ | YES | Only a JSON object is accepted as argument [#]_ |\n+------------------------+------------------------+------------------------------------------------------+\n| `Multipaths`_ | YES | Object keys, if specified, must be JSON strings [#]_ |\n+------------------------+------------------------+------------------------------------------------------+\n| `Literals`_ | YES | Including infinite and NaN values [#]_ |\n+------------------------+------------------------+------------------------------------------------------+\n| `JSON Lines`_ | YES | CLI support [#]_ [#]_ |\n+------------------------+------------------------+------------------------------------------------------+\n\n.. [#] The queries matching is based on Python's operator and as such the results might be different than the ones from\n the Go GJSON package. In particular for the ``~`` operator that checks the truthy-ness of objects.\n.. [#] When using nested queries, only the outermost one controls whether to return only the first item or all items.\n.. [#] Custom modifiers names cannot contain reserved characters used by the GJSON grammar.\n.. [#] For example ``{\"years\":age}`` is valid while ``{years:age}`` is not, although that's valid in GJSON.\n.. [#] Those special cases are handled according to `Python's JSON documentation`_.\n.. [#] Both for applying the same query to each line using the ``-l/--lines`` argument and to automatically encapsulate\n the input lines in a list and apply the query to the list using the ``..`` special query prefix described in\n `JSON Lines`_.\n.. [#] Library support is not currently present because gjson-py accepts only Python objects, making it impossible to\n pass JSON Lines directly. The client is free to choose if calling gjson-py for each line or to encapsulate them in\n a list before calling gjson-py.\n\nThis is the list of modifiers present in GJSON and how they are supported by gjson-py:\n\n+----------------+-----------------------+------------------------------------------+\n| GJSON Modifier | Supported by gjson-py | Notes |\n+----------------+-----------------------+------------------------------------------+\n| ``@reverse`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n| ``@ugly`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n| ``@pretty`` | PARTIALLY | The ``width`` argument is not supported |\n+----------------+-----------------------+------------------------------------------+\n| ``@this`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n| ``@valid`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n| ``@flatten`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n| ``@join`` | PARTIALLY | Preserving duplicate keys not supported |\n+----------------+-----------------------+------------------------------------------+\n| ``@keys`` | YES | Valid only on JSON objects (mappings) |\n+----------------+-----------------------+------------------------------------------+\n| ``@values`` | YES | Valid only on JSON objects (mappings) |\n+----------------+-----------------------+------------------------------------------+\n| ``@tostr`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n| ``@fromstr`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n| ``@group`` | YES | |\n+----------------+-----------------------+------------------------------------------+\n\n\nAdditional features\n^^^^^^^^^^^^^^^^^^^\n\n\nAdditional modifiers\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nThis is the list of additional modifiers specific to gjson-py not present in GJSON:\n\n* ``@ascii``: escapes all non-ASCII characters when printing/returning the string representation of the object,\n ensuring that the output is made only of ASCII characters. It's implemented using the ``ensure_ascii`` arguments in\n the Python's ``json`` module. This modifier doesn't accept any arguments.\n* ``@sort``: sorts a mapping object by its keys or a sequence object by its values. This modifier doesn't accept any\n arguments.\n* ``@top_n``: given a sequence object groups the items in the sequence counting how many occurrences of each value are\n present. It returns a mapping object where the keys are the distinct values of the list and the values are the number\n of times the key was present in the list, ordered from the most common to the least common item. The items in the\n original sequence object must be Python hashable. This modifier accepts an optional argument ``n`` to return just the\n N items with the higher counts. When the ``n`` argument is not provided all items are returned. Example usage:\n\n .. code-block:: console\n\n $ echo '[\"a\", \"b\", \"c\", \"b\", \"c\", \"c\"]' | gjson '@top_n'\n {\"c\": 3, \"b\": 2, \"a\": 1}\n $ echo '[\"a\", \"b\", \"c\", \"b\", \"c\", \"c\"]' | gjson '@top_n:{\"n\":2}'\n {\"c\": 3, \"b\": 2}\n\n* ``@sum_n``: given a sequence of objects, groups the items in the sequence using a grouping key and sum the values of a\n sum key provided. It returns a mapping object where the keys are the distinct values of the grouping key and the\n values are the sums of all the values of the sum key for each distinct grouped key, ordered from the highest sum to\n the lowest. The values of the grouping key must be Python hashable. The values of the sum key must be integers or\n floats. This modifier required two mandatory arguments, ``group`` and ``sum`` that have as values the respective keys\n in the objects of the sequence. An optional ``n`` argument is also accepted to return just the top N items with the\n highest sum. Example usage:\n\n .. code-block:: console\n\n $ echo '[{\"key\": \"a\", \"time\": 1}, {\"key\": \"b\", \"time\": 2}, {\"key\": \"c\", \"time\": 3}, {\"key\": \"a\", \"time\": 4}]' > test.json\n $ gjson test.json '@sum_n:{\"group\": \"key\", \"sum\": \"time\"}'\n {\"a\": 5, \"c\": 3, \"b\": 2}\n $ gjson test.json '@sum_n:{\"group\": \"key\", \"sum\": \"time\", \"n\": 2}'\n {\"a\": 5, \"c\": 3}\n\n.. _`GJSON`: https://github.com/tidwall/gjson\n.. _`Python Package Index`: https://pypi.org/project/gjson/\n.. _`GJSON Path Syntax`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md\n.. _`gjson-py documentation`: https://volans-.github.io/gjson-py/index.html\n.. _`releases page on GitHub`: https://github.com/volans-/gjson-py/releases\n.. _`Python's JSON documentation`: https://docs.python.org/3/library/json.html#infinite-and-nan-number-values\n\n.. _`Path Structure`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#path-structure\n.. _`Basic`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#basic\n.. _`Wildcards`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#wildcards\n.. _`Escape Character`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#escape-character\n.. _`Arrays`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#arrays\n.. _`Queries`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#queries\n.. _`Dot vs Pipe`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#dot-vs-pipe\n.. _`Modifiers`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#modifiers\n.. _`Modifier arguments`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#modifiers\n.. _`Custom modifiers`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#custom-modifiers\n.. _`Multipaths`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#multipaths\n.. _`Literals`: https://github.com/tidwall/gjson/blob/master/SYNTAX.md#literals\n.. _`JSON Lines`: https://github.com/tidwall/gjson#json-lines\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "gjson-py is a Python package that provides a simple way to filter and extract data from JSON-like objects or JSON files, using the GJSON syntax.",
"version": "1.0.0",
"split_keywords": [
"gjson",
"json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad9c22cf9e760d5f7978af70e3e02f585233cf25a2eadebe60eb549e7294ebd6",
"md5": "98c09f1ac9845b264c05fe7673d97689",
"sha256": "8ca97b464708cf9ec629de712f0474e897c5435db2ae3550a604af745617aec6"
},
"downloads": -1,
"filename": "gjson-1.0.0-py3-none-any.whl",
"has_sig": true,
"md5_digest": "98c09f1ac9845b264c05fe7673d97689",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 35890,
"upload_time": "2023-01-24T11:58:45",
"upload_time_iso_8601": "2023-01-24T11:58:45.873177Z",
"url": "https://files.pythonhosted.org/packages/ad/9c/22cf9e760d5f7978af70e3e02f585233cf25a2eadebe60eb549e7294ebd6/gjson-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d77e2d99200e3fa2a8a1b01230ed84c06a6fb15726fd1e070f1c32f7b0df2e9a",
"md5": "98e91f7f6f7cb2f834ad7188ab33d375",
"sha256": "3af9217cfbe2e8d1a9c8203f6fd793838a2e5cbe58dd2b772c4c5f491c55065f"
},
"downloads": -1,
"filename": "gjson-1.0.0.tar.gz",
"has_sig": true,
"md5_digest": "98e91f7f6f7cb2f834ad7188ab33d375",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 57885,
"upload_time": "2023-01-24T11:58:48",
"upload_time_iso_8601": "2023-01-24T11:58:48.054839Z",
"url": "https://files.pythonhosted.org/packages/d7/7e/2d99200e3fa2a8a1b01230ed84c06a6fb15726fd1e070f1c32f7b0df2e9a/gjson-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-24 11:58:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "volans-",
"github_project": "gjson-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "gjson"
}
