openvpn-status-reader 0.3.0__tar.gz

openvpn_status_reader-0.3.0/AUTHORS.rst

@@ -0,0 +1 @@
+- Jiangge Zhang <tonyseek@gmail.com>

openvpn_status_reader-0.3.0/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) Jiangge Zhang
+
+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.

openvpn_status_reader-0.3.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: openvpn-status-reader
+Version: 0.3.0
+Summary: Parse OpenVPN status logs in Python
+Home-page: https://github.com/openwisp/openvpn-status-reader
+Author: OpenWISP
+Author-email: support@openwisp.org
+License: MIT
+Keywords: openvpn,status,log
+Platform: Any
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Internet :: Log Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: humanize<5,>=4.16
+Requires-Dist: netaddr<2,>=1.3
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+OpenVPN Status Reader
+=====================
+
+.. image:: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml/badge.svg?branch=master
+    :target: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml
+    :alt: CI build status
+
+.. image:: https://coveralls.io/repos/openwisp/openvpn-status-reader/badge.svg
+    :target: https://coveralls.io/r/openwisp/openvpn-status-reader
+
+.. image:: https://img.shields.io/librariesio/release/github/openwisp/openvpn-status-reader
+    :target: https://libraries.io/github/openwisp/openvpn-status-reader#repository_dependencies
+    :alt: Dependency monitoring
+
+.. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat-square
+    :target: https://gitter.im/openwisp/general
+
+.. image:: https://badge.fury.io/py/openvpn-status-reader.svg
+    :target: https://badge.fury.io/py/openvpn-status-reader
+
+.. image:: https://pepy.tech/badge/openvpn-status-reader
+    :target: https://pepy.tech/project/openvpn-status-reader
+    :alt: downloads
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://pypi.org/project/black/
+    :alt: code style: black
+
+.. summary-begin
+
+**openvpn-status-reader** is an OpenWISP-maintained Python library for
+parsing OpenVPN status-version-1 logs into Python data structures. It
+supports both legacy and current numeric OpenVPN timestamps.
+
+.. summary-end
+
+This project is a fork of the original openvpn-status_ repository. It
+retains the ``openvpn_status`` import namespace for compatibility.
+
+It supports Python 3.11 and newer.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install openvpn-status-reader
+
+Don't forget to put it in ``setup.py`` / ``requirements.txt``.
+
+Getting Started
+---------------
+
+You could configure your OpenVPN server to log for client status. In usual
+it could be achieved by adding ``status /path/to/openvpn-status.log`` line
+to ``/etc/openvpn/openvpn.conf``. For example:
+
+::
+
+    proto udp
+    port 1194
+    dev tun0
+    status /var/run/openvpn-status.log
+
+Once OpenVPN server running, the log file will be created and written. It
+looks like:
+
+::
+
+    OpenVPN CLIENT LIST
+    Updated,Thu Jun 18 08:12:15 2015
+    Common Name,Real Address,Bytes Received,Bytes Sent,Connected Since
+    foo@example.com,10.10.10.10:49502,334948,1973012,Thu Jun 18 04:23:03 2015
+    bar@example.com,10.10.10.10:64169,1817262,28981224,Thu Jun 18 04:08:39 2015
+    ROUTING TABLE
+    Virtual Address,Common Name,Real Address,Last Ref
+    192.168.255.134,foo@example.com,10.10.10.10:49502,Thu Jun 18 08:12:09 2015
+    192.168.255.126,bar@example.com,10.10.10.10:64169,Thu Jun 18 08:11:55 2015
+    GLOBAL STATS
+    Max bcast/mcast queue length,0
+    END
+
+Now we could parse log file with this library:
+
+.. code-block:: python
+
+    from openvpn_status import parse_status
+
+    with open("/var/run/openvpn-status.log") as logfile:
+        status = parse_status(logfile.read())
+
+    print(status.updated_at)  # datetime.datetime(2015, 6, 18, 8, 12, 15)
+
+    foo_client = status.client_list["169.254.0.1"]
+    print(foo_client.common_name)  # foo@example.com
+    print(foo_client.bytes_received)  # 334.9 kB
+    print(foo_client.bytes_sent)  # 2.0 MB
+    print(int(foo_client.bytes_sent))  # 2097152
+
+More details are in the `API reference`_.
+
+.. _api reference: https://openvpn-status-reader.readthedocs.io/en/latest/api.html
+
+.. _openvpn-status: https://github.com/sgares/openvpn-status

openvpn_status_reader-0.3.0/README.rst

@@ -0,0 +1,104 @@
+OpenVPN Status Reader
+=====================
+
+.. image:: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml/badge.svg?branch=master
+    :target: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml
+    :alt: CI build status
+
+.. image:: https://coveralls.io/repos/openwisp/openvpn-status-reader/badge.svg
+    :target: https://coveralls.io/r/openwisp/openvpn-status-reader
+
+.. image:: https://img.shields.io/librariesio/release/github/openwisp/openvpn-status-reader
+    :target: https://libraries.io/github/openwisp/openvpn-status-reader#repository_dependencies
+    :alt: Dependency monitoring
+
+.. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat-square
+    :target: https://gitter.im/openwisp/general
+
+.. image:: https://badge.fury.io/py/openvpn-status-reader.svg
+    :target: https://badge.fury.io/py/openvpn-status-reader
+
+.. image:: https://pepy.tech/badge/openvpn-status-reader
+    :target: https://pepy.tech/project/openvpn-status-reader
+    :alt: downloads
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://pypi.org/project/black/
+    :alt: code style: black
+
+.. summary-begin
+
+**openvpn-status-reader** is an OpenWISP-maintained Python library for
+parsing OpenVPN status-version-1 logs into Python data structures. It
+supports both legacy and current numeric OpenVPN timestamps.
+
+.. summary-end
+
+This project is a fork of the original openvpn-status_ repository. It
+retains the ``openvpn_status`` import namespace for compatibility.
+
+It supports Python 3.11 and newer.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install openvpn-status-reader
+
+Don't forget to put it in ``setup.py`` / ``requirements.txt``.
+
+Getting Started
+---------------
+
+You could configure your OpenVPN server to log for client status. In usual
+it could be achieved by adding ``status /path/to/openvpn-status.log`` line
+to ``/etc/openvpn/openvpn.conf``. For example:
+
+::
+
+    proto udp
+    port 1194
+    dev tun0
+    status /var/run/openvpn-status.log
+
+Once OpenVPN server running, the log file will be created and written. It
+looks like:
+
+::
+
+    OpenVPN CLIENT LIST
+    Updated,Thu Jun 18 08:12:15 2015
+    Common Name,Real Address,Bytes Received,Bytes Sent,Connected Since
+    foo@example.com,10.10.10.10:49502,334948,1973012,Thu Jun 18 04:23:03 2015
+    bar@example.com,10.10.10.10:64169,1817262,28981224,Thu Jun 18 04:08:39 2015
+    ROUTING TABLE
+    Virtual Address,Common Name,Real Address,Last Ref
+    192.168.255.134,foo@example.com,10.10.10.10:49502,Thu Jun 18 08:12:09 2015
+    192.168.255.126,bar@example.com,10.10.10.10:64169,Thu Jun 18 08:11:55 2015
+    GLOBAL STATS
+    Max bcast/mcast queue length,0
+    END
+
+Now we could parse log file with this library:
+
+.. code-block:: python
+
+    from openvpn_status import parse_status
+
+    with open("/var/run/openvpn-status.log") as logfile:
+        status = parse_status(logfile.read())
+
+    print(status.updated_at)  # datetime.datetime(2015, 6, 18, 8, 12, 15)
+
+    foo_client = status.client_list["169.254.0.1"]
+    print(foo_client.common_name)  # foo@example.com
+    print(foo_client.bytes_received)  # 334.9 kB
+    print(foo_client.bytes_sent)  # 2.0 MB
+    print(int(foo_client.bytes_sent))  # 2097152
+
+More details are in the `API reference`_.
+
+.. _api reference: https://openvpn-status-reader.readthedocs.io/en/latest/api.html
+
+.. _openvpn-status: https://github.com/sgares/openvpn-status

openvpn_status_reader-0.3.0/openvpn_status/__init__.py

@@ -0,0 +1,5 @@
+from .parser import ParsingError
+from .shortcuts import parse_status
+from .version import __version__
+
+__all__ = ["parse_status", "ParsingError", "__version__"]

openvpn_status_reader-0.3.0/openvpn_status/descriptors.py

@@ -0,0 +1,51 @@
+class LabelProperty:
+    """The property with label name."""
+
+    def __init__(self, label, default=None, input_type=None):
+        self.label = label
+        self.default = default
+        self.input_type = input_type
+        self.__name__ = None
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        if self.__name__ in instance.__dict__:
+            return instance.__dict__[self.__name__]
+        elif self.default is not None:
+            value = self.default()
+            instance.__dict__[self.__name__] = value
+            return value
+        else:
+            names = (owner.__name__, self.__name__)
+            raise AttributeError("%r object has no attribute %r" % names)
+
+    def __set__(self, instance, value):
+        if self.input_type is not None:
+            try:
+                value = self.input_type(value)
+            except ValueError as e:
+                raise AssignmentValueError(e)
+        instance.__dict__[self.__name__] = value
+
+
+_missing = object()
+
+
+def name_descriptors(cls):
+    for name, value in iter_descriptors(cls):
+        if getattr(value, "__name__", _missing) is None:
+            value.__name__ = name
+    return cls
+
+
+def iter_descriptors(cls):
+    for name, value in cls.__dict__.items():
+        if name.startswith("__"):
+            continue
+        if getattr(value, "__get__", None) or getattr(value, "__set__", None):
+            yield name, value
+
+
+class AssignmentValueError(ValueError):
+    pass

openvpn_status_reader-0.3.0/openvpn_status/models.py

@@ -0,0 +1,44 @@
+from collections import OrderedDict
+
+from .descriptors import LabelProperty, name_descriptors
+from .utils import parse_filesize, parse_peer, parse_time, parse_vaddr
+
+
+@name_descriptors
+class Status:
+    """The OpenVPN status model."""
+
+    client_list = LabelProperty("OpenVPN CLIENT LIST", OrderedDict)
+    routing_table = LabelProperty("ROUTING TABLE", OrderedDict)
+    global_stats = LabelProperty("GLOBAL STATS")
+    updated_at = LabelProperty("Updated", input_type=parse_time)
+
+
+@name_descriptors
+class Client:
+    """The OpenVPN client model."""
+
+    common_name = LabelProperty("Common Name")
+    real_address = LabelProperty("Real Address", input_type=parse_peer)
+    bytes_received = LabelProperty("Bytes Received", input_type=parse_filesize)
+    bytes_sent = LabelProperty("Bytes Sent", input_type=parse_filesize)
+    connected_since = LabelProperty("Connected Since", input_type=parse_time)
+
+
+@name_descriptors
+class Routing:
+    """The OpenVPN routing model."""
+
+    virtual_address = LabelProperty("Virtual Address", input_type=parse_vaddr)
+    common_name = LabelProperty("Common Name")
+    real_address = LabelProperty("Real Address", input_type=parse_peer)
+    last_ref = LabelProperty("Last Ref", input_type=parse_time)
+
+
+@name_descriptors
+class GlobalStats:
+    """The OpenVPN global stats model."""
+
+    max_bcast_mcast_queue_len = LabelProperty(
+        "Max bcast/mcast queue length", input_type=int
+    )

openvpn_status_reader-0.3.0/openvpn_status/parser.py

@@ -0,0 +1,144 @@
+from collections.abc import Iterator
+
+from .descriptors import AssignmentValueError, iter_descriptors
+from .models import Client, GlobalStats, Routing, Status
+
+
+class LogParser(Iterator):
+    """The parser for parsing OpenVPN status log.
+
+    This kind of parser is stateful. So the :meth:`LogParser.parse` could be
+    called once in the same instance of parser.
+    """
+
+    list_separator = ","
+    line_separator = "\n"
+    terminator = "END"
+
+    def __init__(self, lines):
+        self.lines = iter(lines)
+        self._last_line = None
+        self._rollback = False
+
+    def __next__(self):
+        if self._rollback:
+            self._rollback = False
+            return self._last_line
+        while True:
+            line = next(self.lines).strip()
+            if line:
+                self._last_line = line
+                return line
+
+    @classmethod
+    def fromstring(cls, content):
+        """Creates a parser from content of log.
+
+        :param str content: The log content.
+        :return: The parser instance.
+        """
+        return cls(content.strip().split(cls.line_separator))
+
+    def rollback(self):
+        self._rollback = True
+
+    def expect_line(self, content):
+        try:
+            line = next(self)
+        except StopIteration:
+            raise ParsingError("expected %r but got end of input" % content)
+        if line != content:
+            raise ParsingError("expected %r but got %r" % (content, line))
+
+    def expect_list(self):
+        try:
+            line = next(self)
+        except StopIteration:
+            raise ParsingError("expected list but got end of input")
+        splited = line.split(self.list_separator)
+        if len(splited) == 1:
+            raise ParsingError("expected list but got %r" % line)
+        return splited
+
+    def expect_tuple(self, name):
+        try:
+            line = next(self)
+        except StopIteration:
+            raise ParsingError("expected 2-tuple but got end of input")
+        splited = line.split(self.list_separator)
+        if len(splited) != 2:
+            raise ParsingError("expected 2-tuple but got %r" % line)
+        if splited[0] != name:
+            raise ParsingError("expected 2-tuple starting with %r" % name)
+        return splited[1]
+
+    def parse(self):
+        """Parses the status log.
+
+        :raises ParsingError: if syntax error found in the log.
+        :return: The :class:`.models.Status` with filled data.
+        """
+        try:
+            return self._parse()
+        except AssignmentValueError as e:
+            msg = str(e).encode("ascii", "backslashreplace").decode("ascii")
+            raise ParsingError("expected valid format: %s" % msg)
+
+    def _parse(self):
+        status = Status()
+        self.expect_line(Status.client_list.label)
+
+        status.updated_at = self.expect_tuple(Status.updated_at.label)
+        status.client_list.update(
+            {
+                str(c.real_address): c
+                for c in self._parse_fields(Client, Status.routing_table.label)
+            }
+        )
+        status.routing_table.update(
+            {
+                str(r.virtual_address): r
+                for r in self._parse_fields(Routing, Status.global_stats.label)
+            }
+        )
+        status.global_stats = GlobalStats()
+        status.global_stats.max_bcast_mcast_queue_len = self.expect_tuple(
+            GlobalStats.max_bcast_mcast_queue_len.label
+        )
+
+        self.expect_line(self.terminator)
+        return status
+
+    def _parse_fields(self, cls, next_line):
+        labels = self.expect_list()
+        descriptors = iter_descriptors(cls)
+        label_to_name = {descriptor.label: name for name, descriptor in descriptors}
+        if len(labels) != len(label_to_name) or set(labels) != set(label_to_name):
+            raise ParsingError("invalid fields for %s" % cls.__name__)
+        index_to_name = {
+            index: label_to_name[label] for index, label in enumerate(labels)
+        }
+
+        while True:
+            try:
+                values = self.expect_list()
+            except ParsingError as list_error:
+                try:
+                    self.rollback()
+                    self.expect_line(next_line)
+                except ParsingError as line_error:
+                    raise ParsingError(*(list_error.args + line_error.args))
+                else:
+                    break
+
+            if len(values) != len(index_to_name):
+                raise ParsingError("invalid fields for %s" % cls.__name__)
+            instance = cls()
+            for index, value in enumerate(values):
+                name = index_to_name[index]
+                setattr(instance, name, value)
+            yield instance
+
+
+class ParsingError(Exception):
+    pass

openvpn_status_reader-0.3.0/openvpn_status/shortcuts.py

@@ -0,0 +1,16 @@
+from .parser import LogParser
+
+
+def parse_status(status_log, encoding="utf-8"):
+    """Parses the status log of OpenVPN.
+
+    :param status_log: The content of status log.
+    :type status_log: :class:`str`
+    :param encoding: Optional. The encoding of status log.
+    :type encoding: :class:`str`
+    :return: The instance of :class:`.models.Status`
+    """
+    if isinstance(status_log, bytes):
+        status_log = status_log.decode(encoding)
+    parser = LogParser.fromstring(status_log)
+    return parser.parse()

openvpn_status_reader-0.3.0/openvpn_status/utils.py

@@ -0,0 +1,82 @@
+import collections
+import datetime
+import ipaddress
+import re
+
+from humanize.filesize import naturalsize
+from netaddr import EUI, mac_unix
+
+DATETIME_FORMAT_OPENVPN_V2_5 = "%Y-%m-%d %H:%M:%S"
+DATETIME_FORMAT_OPENVPN_V2_4 = "%a %b %d %H:%M:%S %Y"
+RE_VIRTUAL_ADDR_MAC = re.compile(r"^(?:[a-f0-9]{2}:){5}[a-f0-9]{2}(?:@\d+)?$", re.I)
+RE_VIRTUAL_ADDR_NETWORK = re.compile("/(\\d{1,3})$")
+RE_VIRTUAL_ADDR_CLIENT = re.compile("C$")
+
+
+def parse_time(time):
+    """Parses date and time from input string in OpenVPN logging format."""
+    if isinstance(time, datetime.datetime):
+        return time
+    try:
+        # Try the current numeric timestamp before the legacy format.
+        return datetime.datetime.strptime(time, DATETIME_FORMAT_OPENVPN_V2_5)
+    except ValueError:
+        return datetime.datetime.strptime(time, DATETIME_FORMAT_OPENVPN_V2_4)
+
+
+def parse_peer(peer):
+    if isinstance(peer, PeerAddress):
+        return peer
+    host, port = peer.rsplit(":", 1)
+    return PeerAddress(ipaddress.ip_address(host), int(port))
+
+
+def parse_vaddr(virtual_addr):
+    match = RE_VIRTUAL_ADDR_MAC.search(virtual_addr)
+    if match:
+        return EUI(virtual_addr.split("@")[0], dialect=mac_unix)
+
+    match = RE_VIRTUAL_ADDR_NETWORK.search(virtual_addr)
+    if match and 0 < int(match.group(1)) <= 128:
+        return ipaddress.ip_network(virtual_addr)
+
+    match = RE_VIRTUAL_ADDR_CLIENT.search(virtual_addr)
+    if match:
+        return ipaddress.ip_address(RE_VIRTUAL_ADDR_CLIENT.sub("", virtual_addr))
+
+    return ipaddress.ip_address(virtual_addr)
+
+
+def parse_filesize(size):
+    if isinstance(size, FileSize):
+        return size
+    return FileSize(size)
+
+
+class PeerAddress(collections.namedtuple("PeerAddress", "host port")):
+    """The address of peer entity.
+
+    :param host: The host address of peer entity.
+    :type host: :class:`~ipaddress.IPv4Address` or
+                :class:`~ipaddress.IPv6Address`
+    :param port: The port of peer entity.
+    :type port: :class:`int`
+    """
+
+    def __str__(self):
+        return "{0}:{1}".format(self.host, self.port)
+
+
+class FileSize(int):
+    """The size of bytes."""
+
+    def __str__(self):
+        return self.humanize()
+
+    def humanize(self, **kwargs):
+        """Gets the human-friendly representation of file size.
+
+        :param kwargs: All keyword arguments will be passed to
+                       :func:`humanize.filesize.naturalsize`.
+        """
+        return naturalsize(self, **kwargs)

openvpn_status_reader-0.3.0/openvpn_status/version.py

@@ -0,0 +1,16 @@
+VERSION = (0, 3, 0, "final")
+
+
+def get_version():
+    version = "%s.%s.%s" % VERSION[:3]
+    if VERSION[3:] == ("alpha", 0):
+        return "%s pre-alpha" % version
+    if VERSION[3].startswith("post"):
+        return "%s.%s" % (version, VERSION[3])
+    if VERSION[3] != "final":
+        revision = VERSION[4] if len(VERSION) > 4 else 0
+        return "%s%s%s" % (version, VERSION[3][0], revision)
+    return version
+
+
+__version__ = get_version()

openvpn_status_reader-0.3.0/openvpn_status_reader.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: openvpn-status-reader
+Version: 0.3.0
+Summary: Parse OpenVPN status logs in Python
+Home-page: https://github.com/openwisp/openvpn-status-reader
+Author: OpenWISP
+Author-email: support@openwisp.org
+License: MIT
+Keywords: openvpn,status,log
+Platform: Any
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Internet :: Log Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: humanize<5,>=4.16
+Requires-Dist: netaddr<2,>=1.3
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+OpenVPN Status Reader
+=====================
+
+.. image:: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml/badge.svg?branch=master
+    :target: https://github.com/openwisp/openvpn-status-reader/actions/workflows/ci.yml
+    :alt: CI build status
+
+.. image:: https://coveralls.io/repos/openwisp/openvpn-status-reader/badge.svg
+    :target: https://coveralls.io/r/openwisp/openvpn-status-reader
+
+.. image:: https://img.shields.io/librariesio/release/github/openwisp/openvpn-status-reader
+    :target: https://libraries.io/github/openwisp/openvpn-status-reader#repository_dependencies
+    :alt: Dependency monitoring
+
+.. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat-square
+    :target: https://gitter.im/openwisp/general
+
+.. image:: https://badge.fury.io/py/openvpn-status-reader.svg
+    :target: https://badge.fury.io/py/openvpn-status-reader
+
+.. image:: https://pepy.tech/badge/openvpn-status-reader
+    :target: https://pepy.tech/project/openvpn-status-reader
+    :alt: downloads
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://pypi.org/project/black/
+    :alt: code style: black
+
+.. summary-begin
+
+**openvpn-status-reader** is an OpenWISP-maintained Python library for
+parsing OpenVPN status-version-1 logs into Python data structures. It
+supports both legacy and current numeric OpenVPN timestamps.
+
+.. summary-end
+
+This project is a fork of the original openvpn-status_ repository. It
+retains the ``openvpn_status`` import namespace for compatibility.
+
+It supports Python 3.11 and newer.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install openvpn-status-reader
+
+Don't forget to put it in ``setup.py`` / ``requirements.txt``.
+
+Getting Started
+---------------
+
+You could configure your OpenVPN server to log for client status. In usual
+it could be achieved by adding ``status /path/to/openvpn-status.log`` line
+to ``/etc/openvpn/openvpn.conf``. For example:
+
+::
+
+    proto udp
+    port 1194
+    dev tun0
+    status /var/run/openvpn-status.log
+
+Once OpenVPN server running, the log file will be created and written. It
+looks like:
+
+::
+
+    OpenVPN CLIENT LIST
+    Updated,Thu Jun 18 08:12:15 2015
+    Common Name,Real Address,Bytes Received,Bytes Sent,Connected Since
+    foo@example.com,10.10.10.10:49502,334948,1973012,Thu Jun 18 04:23:03 2015
+    bar@example.com,10.10.10.10:64169,1817262,28981224,Thu Jun 18 04:08:39 2015
+    ROUTING TABLE
+    Virtual Address,Common Name,Real Address,Last Ref
+    192.168.255.134,foo@example.com,10.10.10.10:49502,Thu Jun 18 08:12:09 2015
+    192.168.255.126,bar@example.com,10.10.10.10:64169,Thu Jun 18 08:11:55 2015
+    GLOBAL STATS
+    Max bcast/mcast queue length,0
+    END
+
+Now we could parse log file with this library:
+
+.. code-block:: python
+
+    from openvpn_status import parse_status
+
+    with open("/var/run/openvpn-status.log") as logfile:
+        status = parse_status(logfile.read())
+
+    print(status.updated_at)  # datetime.datetime(2015, 6, 18, 8, 12, 15)
+
+    foo_client = status.client_list["169.254.0.1"]
+    print(foo_client.common_name)  # foo@example.com
+    print(foo_client.bytes_received)  # 334.9 kB
+    print(foo_client.bytes_sent)  # 2.0 MB
+    print(int(foo_client.bytes_sent))  # 2097152
+
+More details are in the `API reference`_.
+
+.. _api reference: https://openvpn-status-reader.readthedocs.io/en/latest/api.html
+
+.. _openvpn-status: https://github.com/sgares/openvpn-status

openvpn_status_reader-0.3.0/openvpn_status_reader.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+AUTHORS.rst
+LICENSE
+README.rst
+pyproject.toml
+setup.cfg
+setup.py
+openvpn_status/__init__.py
+openvpn_status/descriptors.py
+openvpn_status/models.py
+openvpn_status/parser.py
+openvpn_status/shortcuts.py
+openvpn_status/utils.py
+openvpn_status/version.py
+openvpn_status_reader.egg-info/PKG-INFO
+openvpn_status_reader.egg-info/SOURCES.txt
+openvpn_status_reader.egg-info/dependency_links.txt
+openvpn_status_reader.egg-info/not-zip-safe
+openvpn_status_reader.egg-info/requires.txt
+openvpn_status_reader.egg-info/top_level.txt
+tests/test_descriptors.py
+tests/test_models.py
+tests/test_package_meta.py
+tests/test_parser.py
+tests/test_utils.py

openvpn_status_reader-0.3.0/openvpn_status_reader.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openvpn_status_reader-0.3.0/openvpn_status_reader.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

openvpn_status_reader-0.3.0/openvpn_status_reader.egg-info/requires.txt

@@ -0,0 +1,2 @@
+humanize<5,>=4.16
+netaddr<2,>=1.3

openvpn_status_reader-0.3.0/openvpn_status_reader.egg-info/top_level.txt

@@ -0,0 +1 @@
+openvpn_status

openvpn_status_reader-0.3.0/pyproject.toml

@@ -0,0 +1,16 @@
+[tool.isort]
+known_first_party = ["openvpn_status"]
+default_section = "THIRDPARTY"
+line_length = 88
+multi_line_output = 3
+use_parentheses = true
+include_trailing_comma = true
+force_grid_wrap = 0
+
+[tool.coverage.run]
+branch = true
+source = ["openvpn_status"]
+omit = ["*/tests/*"]
+
+[tool.docstrfmt]
+extend_exclude = ["**/*.py"]

openvpn_status_reader-0.3.0/setup.cfg

@@ -0,0 +1,14 @@
+[bdist_wheel]
+python_tag = py3
+
+[tool:pytest]
+addopts = --cov openvpn_status
+
+[flake8]
+exclude = setup.py
+max-line-length = 110
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

openvpn_status_reader-0.3.0/setup.py

@@ -0,0 +1,51 @@
+import sys
+
+from setuptools import find_packages, setup
+
+sys.path.insert(0, "openvpn_status")
+from version import get_version
+
+sys.path.remove("openvpn_status")
+
+with open("README.rst") as readme:
+    long_description = readme.read().strip()
+
+
+setup(
+    name="openvpn-status-reader",
+    version=get_version(),
+    url="https://github.com/openwisp/openvpn-status-reader",
+    author="OpenWISP",
+    author_email="support@openwisp.org",
+    description="Parse OpenVPN status logs in Python",
+    long_description=long_description,
+    packages=find_packages(),
+    zip_safe=False,
+    license="MIT",
+    keywords=["openvpn", "status", "log"],
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Intended Audience :: System Administrators",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: 3.14",
+        "Programming Language :: Python :: Implementation :: CPython",
+        "Programming Language :: Python :: Implementation :: PyPy",
+        "Topic :: Internet :: Log Analysis",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "Topic :: System :: Logging",
+        "Topic :: Text Processing",
+        "Topic :: Utilities",
+    ],
+    install_requires=[
+        "humanize>=4.16,<5",
+        "netaddr>=1.3,<2",
+    ],
+    python_requires=">=3.11",
+    platforms=["Any"],
+)

openvpn_status_reader-0.3.0/tests/test_descriptors.py

@@ -0,0 +1,38 @@
+from pytest import fixture, raises
+
+from openvpn_status.descriptors import LabelProperty, iter_descriptors, name_descriptors
+
+
+@fixture
+def foo_class():
+    @name_descriptors
+    class Foo:
+        foo = LabelProperty("Foo")
+        bar = LabelProperty("Bar", default=lambda: 0, input_type=int)
+        baz = property(lambda self: self.bar)
+        biu = ()
+
+    return Foo
+
+
+def test_label_and_its_name(foo_class):
+    foo = foo_class()
+    with raises(AttributeError):
+        foo.foo
+    assert foo.bar == 0
+    assert foo.baz == 0
+
+    foo.foo = "1"
+    foo.bar = "2"
+
+    assert foo.foo == "1"
+    assert foo.bar == 2
+    assert foo.baz == 2
+
+
+def test_iter_descriptors(foo_class):
+    assert dict(iter_descriptors(foo_class)) == {
+        "foo": foo_class.foo,
+        "bar": foo_class.bar,
+        "baz": foo_class.baz,
+    }

openvpn_status_reader-0.3.0/tests/test_models.py

@@ -0,0 +1,105 @@
+from collections import OrderedDict
+from datetime import datetime
+from ipaddress import IPv4Address
+from itertools import combinations
+
+from openvpn_status.models import Client, GlobalStats, Routing, Status
+
+
+def is_inequality(iterable):
+    return all(left != right for left, right in combinations(iterable, 2))
+
+
+def test_status():
+    status = Status()
+    assert isinstance(status.client_list, OrderedDict)
+    assert isinstance(status.routing_table, OrderedDict)
+
+    assert getattr(status, "client_list", None) is not None
+    assert getattr(status, "routing_table", None) is not None
+    assert getattr(status, "global_stats", None) is None
+    assert getattr(status, "updated_at", None) is None
+
+    now = datetime.now()
+    status.updated_at = now
+    assert status.updated_at == now
+
+
+def test_status_properties():
+    status = Status()
+    status.client_list.update((i, i) for i in range(3))
+    assert len(status.client_list) == 3
+    assert status.client_list[0] == 0
+    assert status.client_list[1] == 1
+    assert status.client_list[2] == 2
+
+
+def test_status_labels():
+    assert is_inequality(
+        [
+            Status.client_list.label,
+            Status.routing_table.label,
+            Status.global_stats.label,
+        ]
+    )
+
+
+def test_client():
+    client = Client()
+    assert getattr(client, "common_name", None) is None
+    assert getattr(client, "real_address", None) is None
+    assert getattr(client, "bytes_received", None) is None
+    assert getattr(client, "bytes_sent", None) is None
+    assert getattr(client, "connected_since", None) is None
+
+    client.bytes_received = 532895
+    assert client.bytes_received.humanize() == "532.9 kB"
+
+    client.bytes_sent = 34254
+    assert client.bytes_received.humanize(gnu=True) == "520.4K"
+
+
+def test_client_labels():
+    assert is_inequality(
+        [
+            Client.common_name.label,
+            Client.real_address.label,
+            Client.bytes_received.label,
+            Client.bytes_sent.label,
+            Client.connected_since.label,
+        ]
+    )
+
+
+def test_routing():
+    routing = Routing()
+    assert getattr(routing, "virtual_address", None) is None
+    assert getattr(routing, "common_name", None) is None
+    assert getattr(routing, "real_address", None) is None
+    assert getattr(routing, "last_ref", None) is None
+
+    routing.virtual_address = "172.16.1.1"
+    assert routing.virtual_address == IPv4Address("172.16.1.1")
+
+    routing.real_address = "192.168.1.1:8080"
+    assert routing.real_address.host == IPv4Address("192.168.1.1")
+    assert routing.real_address.port == 8080
+
+
+def test_routing_labels():
+    assert is_inequality(
+        [
+            Routing.virtual_address.label,
+            Routing.common_name.label,
+            Routing.real_address,
+            Routing.last_ref,
+        ]
+    )
+
+
+def test_global_stats():
+    global_stats = GlobalStats()
+    assert getattr(global_stats, "max_bcast_mcast_queue_len", None) is None
+
+    global_stats.max_bcast_mcast_queue_len = 0
+    assert global_stats.max_bcast_mcast_queue_len == 0

openvpn_status_reader-0.3.0/tests/test_package_meta.py

@@ -0,0 +1,31 @@
+from pytest import mark, raises
+
+import openvpn_status
+from openvpn_status import version as version_module
+from openvpn_status.version import VERSION, get_version
+
+
+def test_version():
+    assert VERSION == (0, 3, 0, "final")
+    assert openvpn_status.__version__ == "0.3.0"
+
+
+def test_shortcut():
+    with raises(openvpn_status.ParsingError):
+        openvpn_status.parse_status("")
+    with raises(openvpn_status.ParsingError):
+        openvpn_status.parse_status(b"")
+
+
+@mark.parametrize(
+    "version, expected",
+    [
+        ((1, 2, 3, "alpha", 0), "1.2.3 pre-alpha"),
+        ((1, 2, 3, "post1"), "1.2.3.post1"),
+        ((1, 2, 3, "beta", 4), "1.2.3b4"),
+        ((1, 2, 3, "rc"), "1.2.3r0"),
+    ],
+)
+def test_get_version(monkeypatch, version, expected):
+    monkeypatch.setattr(version_module, "VERSION", version)
+    assert get_version() == expected

openvpn_status_reader-0.3.0/tests/test_parser.py

@@ -0,0 +1,141 @@
+import datetime
+import ipaddress
+
+from netaddr import EUI
+from pytest import fixture, mark, raises
+
+from openvpn_status.parser import LogParser, ParsingError
+
+
+@fixture(params=["openvpn-status.txt", "openvpn-status-openvpn-2-7.txt"])
+def openvpn_status(datadir, request):
+    return datadir.join(request.param)
+
+
+@fixture
+def broken_status(datadir):
+    return datadir.join("broken-openvpn-status")
+
+
+def test_parser(openvpn_status):
+    parser = LogParser.fromstring(openvpn_status.read())
+    status = parser.parse()
+
+    assert len(status.client_list) == 5
+    assert len(status.routing_table) == 9
+
+    assert status.global_stats.max_bcast_mcast_queue_len == 0
+    assert status.updated_at == datetime.datetime(2015, 6, 18, 8, 12, 15)
+
+    client = status.client_list["10.10.10.10:49502"]
+    assert client.common_name == "foo@example.com"
+    assert str(client.real_address) == "10.10.10.10:49502"
+    assert str(client.real_address.host) == "10.10.10.10"
+    assert client.real_address.port == 49502
+    assert client.connected_since == datetime.datetime(2015, 6, 18, 4, 23, 3)
+    assert client.bytes_received == 334948
+    assert client.bytes_sent == 1973012
+
+    tun_routing = status.routing_table["192.168.255.134"]
+    assert isinstance(tun_routing.virtual_address, ipaddress.IPv4Address)
+    assert str(tun_routing.virtual_address) == "192.168.255.134"
+    assert tun_routing.common_name == "foo@example.com"
+    assert str(tun_routing.real_address) == "10.10.10.10:49502"
+    assert tun_routing.last_ref == datetime.datetime(2015, 6, 18, 8, 12, 9)
+
+    tap_routing = status.routing_table["22:1d:63:bf:62:38"]
+    assert isinstance(tap_routing.virtual_address, EUI)
+    assert str(tap_routing.virtual_address) == "22:1d:63:bf:62:38"
+    assert tap_routing.common_name == "tap@example.com"
+    assert str(tap_routing.real_address) == "10.0.0.100:55712"
+    assert tap_routing.last_ref == datetime.datetime(2017, 10, 19, 20, 14, 19)
+
+    ccd_routing = status.routing_table["10.200.0.0/16"]
+    assert isinstance(ccd_routing.virtual_address, ipaddress.IPv4Network)
+    assert str(ccd_routing.virtual_address) == "10.200.0.0/16"
+    assert ccd_routing.common_name == "baz@example.com"
+    assert str(ccd_routing.real_address) == "10.10.10.10:63414"
+    assert ccd_routing.last_ref == datetime.datetime(2015, 6, 18, 8, 12, 9)
+
+    ccd_v6_routing = status.routing_table["2001:db8::1000/124"]
+    assert isinstance(ccd_v6_routing.virtual_address, ipaddress.IPv6Network)
+    assert str(ccd_v6_routing.virtual_address) == "2001:db8::1000/124"
+    assert ccd_v6_routing.common_name == "baz@example.com"
+    assert str(ccd_v6_routing.real_address) == "10.10.10.10:63414"
+    assert ccd_v6_routing.last_ref == datetime.datetime(2015, 6, 18, 8, 12, 9)
+
+
+def test_parser_with_syntax_errors(broken_status):
+    def catch_syntax_error(seq):
+        datafile = broken_status.join("%d.txt" % seq)
+        parser = LogParser.fromstring(datafile.read())
+        with raises(ParsingError) as error:
+            parser.parse()
+        return error
+
+    error = catch_syntax_error(0)
+    assert not error.value.args[0].startswith("expected list")
+    assert not error.value.args[0].startswith("expected 2-tuple")
+    assert error.value.args[0].endswith("got end of input")
+
+    error = catch_syntax_error(1)
+    assert not error.value.args[0].startswith("expected list")
+    assert not error.value.args[0].startswith("expected 2-tuple")
+    assert error.value.args[0].endswith("got %r" % "BrokenVPN CLIENT LIST")
+
+    error = catch_syntax_error(2)
+    assert error.value.args[0] == "expected list but got end of input"
+
+    error = catch_syntax_error(3)
+    assert error.value.args[0] == "expected 2-tuple but got end of input"
+
+    error = catch_syntax_error(4)
+    assert error.value.args[0] == "expected 2-tuple but got %r" % "Updated,Yo,Hoo"
+
+    error = catch_syntax_error(5)
+    assert error.value.args[0] == "expected 2-tuple starting with %r" % "Updated"
+
+    error = catch_syntax_error(6)
+    assert error.value.args[0] == "expected list but got %r" % "YO TABLE"
+
+    error = catch_syntax_error(7)
+    assert error.value.args[0].startswith("expected valid format: time data ")
+
+
+@mark.parametrize(
+    "labels,values",
+    [
+        (
+            [
+                "Common Name",
+                "Real Address",
+                "Bytes Received",
+                "Bytes Sent",
+                "Unexpected",
+            ],
+            ["foo", "10.10.10.10:49502", "1", "1", "value"],
+        ),
+        (
+            [
+                "Common Name",
+                "Real Address",
+                "Bytes Received",
+                "Bytes Sent",
+                "Connected Since",
+            ],
+            ["foo", "10.10.10.10:49502", "1", "1", "2026-10-20 17:48:08", "extra"],
+        ),
+    ],
+)
+def test_parser_rejects_invalid_field_schema(labels, values):
+    content = "\n".join(
+        [
+            "OpenVPN CLIENT LIST",
+            "Updated,2026-10-20 17:48:08",
+            ",".join(labels),
+            ",".join(values),
+        ]
+    )
+
+    with raises(ParsingError, match="invalid fields"):
+        LogParser.fromstring(content).parse()

openvpn_status_reader-0.3.0/tests/test_utils.py

@@ -0,0 +1,75 @@
+from datetime import datetime
+from ipaddress import IPv4Address, IPv4Network, IPv6Address, IPv6Network
+
+from netaddr import EUI, mac_unix
+from pytest import mark
+
+from openvpn_status.utils import (
+    FileSize,
+    PeerAddress,
+    parse_filesize,
+    parse_peer,
+    parse_time,
+    parse_vaddr,
+)
+
+
+@mark.parametrize(
+    "text,time",
+    [
+        ("Thu Jun 18 04:23:03 2015", datetime(2015, 6, 18, 4, 23, 3)),
+        ("Thu Jun 18 04:08:39 2015", datetime(2015, 6, 18, 4, 8, 39)),
+        ("Thu Jun 18 07:57:25 2015", datetime(2015, 6, 18, 7, 57, 25)),
+        ("2026-10-20 17:48:08", datetime(2026, 10, 20, 17, 48, 8)),
+        (datetime(2015, 6, 18, 7, 57, 25), datetime(2015, 6, 18, 7, 57, 25)),
+    ],
+)
+def test_parse_time(text, time):
+    assert parse_time(text) == time
+
+
+@mark.parametrize(
+    "text,peer",
+    [
+        ("10.0.0.1:49502", PeerAddress(IPv4Address("10.0.0.1"), 49502)),
+        ("10.0.0.2:64169", PeerAddress(IPv4Address("10.0.0.2"), 64169)),
+        ("10.0.0.3:63414", PeerAddress(IPv4Address("10.0.0.3"), 63414)),
+        (PeerAddress("10.0.0.1", 80), PeerAddress("10.0.0.1", 80)),
+    ],
+)
+def test_parse_peer(text, peer):
+    assert parse_peer(text) == peer
+    assert str(text) == str(peer)
+
+
+@mark.parametrize(
+    "text,virtual_addr",
+    [
+        ("10.0.0.1", IPv4Address("10.0.0.1")),
+        ("2001:db8:2de::e13", IPv6Address("2001:db8:2de::e13")),
+        ("10.200.0.0/16", IPv4Network("10.200.0.0/16")),
+        ("2001:db8::1000/124", IPv6Network("2001:db8::1000/124")),
+        ("28:d2:44:d4:e6:ea", EUI("28:d2:44:d4:e6:ea", dialect=mac_unix)),
+    ],
+)
+def test_parse_vaddr(text, virtual_addr):
+    assert parse_vaddr(text) == virtual_addr
+    assert str(text) == str(virtual_addr)
+
+
+def test_parse_vaddr_with_interface_index():
+    assert parse_vaddr("28:d2:44:d4:e6:ea@5") == EUI(
+        "28:d2:44:d4:e6:ea", dialect=mac_unix
+    )
+
+
+@mark.parametrize(
+    "text,humanized",
+    [
+        (10240, "10.2 kB"),
+        ("10240", "10.2 kB"),
+        (FileSize(10240), "10.2 kB"),
+    ],
+)
+def test_parse_filesize(text, humanized):
+    assert str(parse_filesize(text)) == humanized