line-protocol-parser 2.0.1__cp315-cp315-win_amd64.whl

line_protocol_parser/__init__.py

@@ -0,0 +1,12 @@
+"""Parse InfluxDB line protocol strings into dictionaries or ``None``."""
+from ._line_protocol_parser import parse_line, LineFormatError
+
+# Module metadata
+__author__ = 'Daniel Andersson'
+__maintainer__ = __author__
+__email__ = 'daniel.4ndersson@gmail.com'
+__contact__ = __email__
+__copyright__ = 'Copyright (c) 2019 Daniel Andersson'
+__license__ = 'MIT'
+__url__ = "https://github.com/Penlect/line-protocol-parser"
+__version__ = '2.0.1'

line_protocol_parser-2.0.1.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: line-protocol-parser
+Version: 2.0.1
+Summary: Parse InfluxDB line protocol string into Python dictionary
+Home-page: https://github.com/Penlect/line-protocol-parser
+Author: Daniel Andersson
+Author-email: daniel.4ndersson@gmail.com
+License: MIT
+Keywords: InfluxDB influx line protocol parser reader
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+License-File: LICENSE.md
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+Welcome to InfluxDB line-protocol-parser
+========================================
+
+Parse InfluxDB `line protocol`_ strings into Python dictionaries.
+
+Example:
+^^^^^^^^
+
+.. code-block:: python
+
+    >>> from line_protocol_parser import parse_line
+    >>> data = parse_line('myMeas,someTag=ABC field1=3.14,field2="Hello, World!" 123')
+    >>> print(data)
+    {'measurement': 'myMeas',
+    'fields': {'field1': 3.14, 'field2': 'Hello, World!'},
+    'tags': {'someTag': 'ABC'},
+    'time': 123}
+
+
+**The InfluxDB line protocol is a text based format for writing points to InfluxDB.
+This project can read this format and convert line strings to Python dicitonaries.**
+
+The line protocol has the following format:
+
+    <measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]
+
+and is documented here: `InfluxDB line protocol`_.
+
+This parser is aligned with archived InfluxDB v1.2 single-line parser
+semantics for standard text inputs. When an input point omits the timestamp,
+``parse_line()`` returns ``None`` for ``time`` so omission remains distinct
+from an explicit ``0`` timestamp. Leading ``#`` comment lines, including
+lines with leading whitespace before ``#``, are treated as valid input and
+``parse_line()`` returns ``None`` for those lines as well. The parser also
+accepts the same top-level whitespace skipping before measurements, fields,
+and timestamps that the archived v1.2 parser tolerated, along with trailing
+spaces after the optional timestamp. The combined measurement/tag key is
+limited to 65535 bytes, matching the archived parser limit.
+Unsigned ``123u`` field values are retained as a package extension even though
+they are not documented in the archived v1.2 reference.
+
+The ``line_protocol_parser`` module only contains the ``parse_line`` function and the ``LineFormatError`` exception which is raised on failure.
+
+Installation
+^^^^^^^^^^^^
+Python 3.10 or newer is required.
+
+From PyPI:
+
+.. code-block:: bash
+
+    $ python3 -m pip install line-protocol-parser
+
+or from source (make sure you have ``python3 -m pip install wheel setuptools`` first):
+
+.. code-block:: bash
+
+    $ git clone https://github.com/Penlect/line-protocol-parser.git
+    $ cd line-protocol-parser
+    $ python3 setup.py bdist_wheel
+    $ python3 -m pip install ./dist/line-protocol-parser-*.whl
+
+or from generated Debian package:
+
+.. code-block:: bash
+
+    # Install build dependencies
+    $ sudo apt install python3-all python3-all-dev python3-setuptools dh-python
+    $ git clone https://github.com/Penlect/line-protocol-parser.git
+    $ cd line-protocol-parser
+    $ make deb
+    $ sudo apt install ./python3-line-protocol-parser_*.deb
+
+Use Case 1: Read points from a file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Suppose you have a text file with influxDB measurement points, "my_influxDB_points.txt"::
+
+    # generated by sensor gateway
+    myMeasurement,someTag=A temperature=37.0 1570977942581909918
+    myMeasurement,someTag=A temperature=37.3 1570977942581910000
+    myMeasurement,someTag=A temperature=36.9 1570977942581912345
+    myMeasurement,someTag=A temperature=37.1 1570977942581923399
+    ...
+
+Then you can load each line into a dicitonary to be printed like this:
+
+.. code-block:: python3
+
+    >>> from line_protocol_parser import parse_line
+    >>> with open('my_influxDB_points.txt', 'r') as f_obj:
+    ...     for line in f_obj:
+    ...         point = parse_line(line)
+    ...         if point is not None:
+    ...             print(point)
+
+
+Use Case 2: InfluxDB subscriptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+InfluxDB subscriptions are documented here: `InfluxDB Subscriptions`_.
+
+InfluxDB subscriptions are local or remote endpoints to which all data written to InfluxDB is copied. Endpoint able to accept UDP, HTTP, or HTTPS connections can subscribe to InfluxDB and receive a copy of all data as it is written.
+
+In this example we will do the following:
+
+1) Setup and run a InfluxDB container.
+2) Create a subscription.
+3) Create a Python server and register it as an endpoint.
+4) Use ``line_protocol_parser`` to read and print incoming data.
+
+**Step 1**. Run the following commands to run a `InfluxDB container`_ and attach to the influx client.
+
+.. code-block:: bash
+
+   $ docker run -d --network="host" --name inf influxdb
+   $ docker exec -it inf influx
+
+
+**Step 2**. Create subscription. Run these commands in the influx client prompt.
+
+
+.. code-block:: bash
+
+   > CREATE DATABASE mydb
+   > USE mydb
+   > CREATE SUBSCRIPTION "mysub" ON "mydb"."autogen" DESTINATIONS ALL 'http://localhost:9090'
+
+Since we used `--network="host"` we can use localhost from inside the container.
+
+**Step 3 & 4**. Python server to receive InfluxDB data.
+
+Create a python file *server.py* with the following content:
+
+.. code-block:: python
+
+    from pprint import pprint
+    from http.server import HTTPServer, BaseHTTPRequestHandler
+    from line_protocol_parser import parse_line
+
+    class PostHandler(BaseHTTPRequestHandler):
+
+        def do_POST(self):
+            content_length = int(self.headers['Content-Length'])
+            post_data = self.rfile.read(content_length)
+            point = parse_line(post_data)
+            if point is not None:
+                pprint(point)
+            self.send_response(200)
+            self.end_headers()
+
+    if __name__ == '__main__':
+        server = HTTPServer(('localhost', 9090), PostHandler)
+        print('Starting server, use <Ctrl-C> to stop')
+        server.serve_forever()
+
+
+Start the server:
+
+.. code-block:: bash
+
+   $ python3 server.py
+   Starting server, use <Ctrl-C> to stop
+
+
+Next, go back to your influx client and insert a data point:
+
+.. code-block:: bash
+
+   > INSERT oven,room=kitchen temperature=225.0 1234567890
+
+Head back to your Python server and watch the output:
+
+.. code-block:: bash
+
+   $ python3 server.py
+   Starting server, use <Ctrl-C> to stop
+   {'fields': {'temperature': 225.0},
+    'measurement': 'oven',
+    'tags': {'room': 'kitchen'},
+    'time': 1234567890}
+   172.17.0.2 - - [14/Oct/2019 21:02:57] "POST /write?consistency=&db=mydb&precision=ns&rp=autogen HTTP/1.1" 200 -
+
+
+Pure C usage
+^^^^^^^^^^^^
+If you are not interested in the Python wrapper you may find the pure-c files useful:
+
+* ``include/line_protocol_parser.h``
+* ``src/line_protocol_parser.c``
+
+The C API keeps the original point-or-error contract. If you want to skip
+leading ``#`` comment lines in C code, filter those lines before calling
+``LP_parse_line()``. The C API accepts NUL-terminated strings only, while the
+Python wrapper rejects embedded NUL bytes instead of silently truncating
+input.
+
+Example:
+
+.. code-block:: c
+
+    int main()
+    {
+        const char *line = "measurement,tag=value field=\"Hello, world!\" 1570283407262541159";
+        struct LP_Point *point;
+        int status = 0;
+        point = LP_parse_line(line, &status);
+        if (point == NULL) {
+            LP_DEBUG_PRINT("ERROR STATUS: %d\n", status);
+        }
+        // < Do something useful with point here >
+        LP_free_point(point);
+        return status;
+    }
+
+Please see the comments in the source and header file for more information.
+
+Examples from the Test Cases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The test cases are a good source of examples. Please see: `tests/test_parse_line.py <tests/test_parse_line.py>`_.
+
+Changelog
+^^^^^^^^^
+The changelog is maintained in the debian directory, please check there: `changelog <debian/changelog>`_.
+
+.. _line protocol: https://archive.docs.influxdata.com/influxdb/v1.2/write_protocols/line_protocol_reference/
+.. _InfluxDB line protocol: https://archive.docs.influxdata.com/influxdb/v1.2/write_protocols/line_protocol_reference/
+.. _InfluxDB Subscriptions: https://docs.influxdata.com/influxdb/latest/administration/subscription-management/
+.. _InfluxDB container: https://hub.docker.com/_/influxdb

line_protocol_parser-2.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+line_protocol_parser/__init__.py,sha256=HQ_2BwTkCwEMljdLVobCaJXNlQWMT_fYOt3hYD0IW8Q,449
+line_protocol_parser/_line_protocol_parser.cp315-win_amd64.pyd,sha256=78oyexPTIGM5S2GYVK1LsG8pEb5dtYxaoVTYL5LYCwE,19968
+line_protocol_parser-2.0.1.dist-info/licenses/LICENSE.md,sha256=ZwCi4PL_jfr7S29_rsDtkAwdETi41TFwhpTDCPuFm0M,1094
+line_protocol_parser-2.0.1.dist-info/METADATA,sha256=NbyLMhUU85tg3gIk7YQxwQ0R7gJNZgc45fyv18Zk0_g,9599
+line_protocol_parser-2.0.1.dist-info/WHEEL,sha256=geuJoH1aW6kS7q0cKuoOBUdE-tpBsTvRf9l5rOGbxQs,101
+line_protocol_parser-2.0.1.dist-info/top_level.txt,sha256=C4XTC2uwMUV0R7rzgFVrjtetkEg2YK8vOeK5C7OuBoQ,21
+line_protocol_parser-2.0.1.dist-info/RECORD,,

line_protocol_parser-2.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: cp315-cp315-win_amd64
+

line_protocol_parser-2.0.1.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Daniel Andersson
+
+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.

line_protocol_parser-2.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+line_protocol_parser