Migrate to a package, add type information

Author: andrivet

.bumpversion.cfg

@@ -1,11 +1,11 @@
 [bumpversion]
-current_version = 3.0.1
+current_version = 3.1.0
 commit = True
 tag = True
 
 [bumpversion:file:setup.py]
 
 [bumpversion:file:docs/conf.py]
 
-[bumpversion:file:src/asn1.py]
+[bumpversion:file:src/asn1/core.py]
 

CHANGELOG.rst

@@ -1,6 +1,11 @@
 Changelog
 =========
 
+3.1.0 (2025-05-16)
+------------------
+
+* #291 - Add support for mypy. As a consequence, the previous module has been migrated to a package.
+
 3.0.1 (2025-05-02)
 ------------------
 

MANIFEST.in

@@ -3,7 +3,6 @@ graft examples
 graft src
 graft ci
 graft tests
-graft stubs
 
 include .coveragerc
 include .cookiecutterrc
@@ -23,5 +22,8 @@ include *.ini
 include *.yml
 include *.yaml
 
+include src/asn1/core.pyi
+include src/asn1/py.typed
+
 global-exclude *.py[cod] __pycache__ *.so *.dylib .DS_Store .mypy_cache
 exclude .python-version

docs/conf.py

@@ -27,7 +27,7 @@
 year = '2007-2022'
 author = 'Sebastien Andrivet'
 copyright = '{0}, {1}'.format(year, author)
-version = release = '3.0.1'
+version = release = '3.1.0'
 
 pygments_style = 'trac'
 templates_path = ['.']

docs/credits.rst

@@ -8,4 +8,4 @@ The following projects have provided inspiration for Python-ASN1:
   building constructed types.
 
 .. _pyasn1: https://pyasn1.sourceforge.net/
-.. _Samba: https://www.samba.org
+.. _Samba: https://github.com/samba-team/samba/tree/master/source3/libads

setup.py

@@ -29,7 +29,7 @@ def read(*names, **kwargs):
 
 setup(
     name='asn1',
-    version='3.0.1',
+    version='3.1.0',
     license='BSD',
     description='Python-ASN1 is a simple ASN.1 encoder and decoder for Python 2.7+ and 3.5+.',
     long_description='%s\n%s' % (
@@ -42,6 +42,7 @@ def read(*names, **kwargs):
     url='https://github.com/andrivet/python-asn1',
     packages=find_packages('src'),
     package_dir={'': 'src'},
+    package_data={'asn1': ['py.typed', 'core.pyi']},
     py_modules=[splitext(basename(path))[0] for path in glob('src/*.py')],
     include_package_data=True,
     zip_safe=False,
@@ -72,9 +73,5 @@ def read(*names, **kwargs):
         # eg: 'keyword1', 'keyword2', 'keyword3',
     ],
     install_requires=install_requires,
-    extras_require={
-        # eg:
-        #   'rst': ['docutils>=0.11'],
-        #   ':python_version=="2.6"': ['argparse'],
-    },
+    extras_require={},
 )

src/asn1/__init__.py

@@ -0,0 +1,11 @@
+from .core import Classes
+from .core import Decoder
+from .core import Encoder
+from .core import Encoding
+from .core import Error
+from .core import Numbers
+from .core import ReadFlags
+from .core import Tag
+from .core import Types
+
+__all__ = ["Decoder", "Encoder", "Numbers", "Types", "Classes", "Encoding", "ReadFlags", "Tag", "Error"]

src/asn1.py renamed to src/asn1/core.py

@@ -28,7 +28,7 @@
 from enum import IntEnum
 from functools import reduce
 
-__version__ = "3.0.1"
+__version__ = "3.1.0"
 
 from typing import Any  # noqa: F401
 from typing import Generator  # noqa: F401
@@ -103,6 +103,7 @@ class Classes(Asn1Enum):
 
 
 class Encoding(Asn1Enum):
+    """ASN.1 encoding types."""
     DER = 1  # Distinguished Encoding Rules
     CER = 2  # Canonical Encoding Rules
 
@@ -119,6 +120,12 @@ class ReadFlags(IntEnum):
 `Decoder.read()`.
 """
 
+EncoderStream = Union[io.RawIOBase, io.BufferedWriter, None]
+"""A stream that can be used for output."""
+
+DecoderStream = Union[io.RawIOBase, io.BufferedIOBase, bytes]
+"""A stream that can be used for input."""
+
 
 def to_int_2c(values):  # type: (bytes) -> int
     """Bytes to integer conversion in two's complement."""
@@ -205,19 +212,19 @@ class Encoder(object):
 
     def __init__(self):  # type: () -> None
         """Constructor."""
-        self._stream = None     # type: Union[io.RawIOBase, io.BufferedWriter, None]  # Output stream
+        self._stream = None     # type: EncoderStream  # Output stream
         self._encoding = None   # type: Union[Encoding, None] # Encoding type (DER or CER)
         self._stack = None      # type: List[List[bytes]] | None  # Stack of encoded data
 
     def start(self, stream=None, encoding=None):
-        # type: (Union[io.RawIOBase, io.BufferedWriter, Encoding, None], Union[Encoding, None]) -> None
+        # type: (EncoderStream, Union[Encoding, None]) -> None
         """
         This method instructs the encoder to start encoding a new ASN.1
         output. This method may be called at any time to reset the encoder
         and reset the current output (if any).
 
         Args:
-            stream (io.RawIOBase or Encoding or None): The output stream or the encoding with no stream.
+            stream (EncoderStream): The output stream or the encoding with no stream.
             encoding (Encoding or None): The encoding (DER or CER) to use.
         """
         # stream is an Encoding, encoding is an Encoding: this not allowed
@@ -724,7 +731,7 @@ def __init__(self):  # type: () -> None
         self._levels = 0        # type: int # Number of recursive calls
         self._ends = []         # type: List[int] # End of the current element (or INDEFINITE_FORM) for enter / leave
 
-    def start(self, stream):  # type: (Union[io.RawIOBase, io.BufferedIOBase, bytes]) -> None
+    def start(self, stream):  # type: (DecoderStream) -> None
         """
         This method instructs the decoder to start decoding an ASN.1 input.
         This method may be called at any time to start a new decoding job.
@@ -736,7 +743,7 @@ def start(self, stream):  # type: (Union[io.RawIOBase, io.BufferedIOBase, bytes]
             assumes the input is in BER or DER format.
 
         Args:
-            stream (bytes or io.RawIOBase): ASN.1 input, in BER or DER format, to be decoded.
+            stream (DecoderStream): ASN.1 input, in BER or DER format, to be decoded.
 
         Returns:
             None
@@ -745,7 +752,7 @@ def start(self, stream):  # type: (Union[io.RawIOBase, io.BufferedIOBase, bytes]
             `Error`
         """
         if not isinstance(stream, bytes) and not isinstance(stream, io.RawIOBase) and not isinstance(stream, io.BufferedIOBase):
-            raise Error('Expecting bytes or a subclass of io.RawIOBase. Get {} instead.'.format(type(stream)))
+            raise Error('Expecting bytes or a subclass of io.RawIOBase or BufferedIOBase. Get {} instead.'.format(type(stream)))
 
         self._stream = io.BytesIO(stream) if isinstance(stream, bytes) else stream  # type: ignore
         self._tag = None

stubs/asn1.pyi renamed to src/asn1/core.pyi

@@ -6,10 +6,6 @@ from typing import Any
 from typing import Generator
 from typing import NamedTuple
 
-from _typeshed import Incomplete
-
-INDEFINITE_FORM: int
-
 class Asn1Enum(IntEnum): ...
 
 class Numbers(Asn1Enum):
@@ -59,29 +55,27 @@ class Classes(Asn1Enum):
     Context = 128
     Private = 192
 
+class Encoding(Asn1Enum):
+    DER = 1
+    CER = 2
+
 class ReadFlags(IntEnum):
     OnlyValue = 0
     WithUnused = 1
 
 class Tag(NamedTuple):
-    nr: Incomplete
-    typ: Incomplete
-    cls: Incomplete
+    nr: int
+    typ: int
+    cls: int
 
-def to_int_2c(values: bytes) -> int: ...
-def to_bytes_2c(value: int) -> bytes: ...
-def shift_bits_right(values, unused): ...
-def is_negative_zero(x): ...
-def is_positive_infinity(x): ...
-def is_negative_infinity(x): ...
-def is_nan(x): ...
-def is_iterable(value): ...
+EncoderStream: io.RawIOBase | io.BufferedWriter | None
+DecoderStream = io.RawIOBase | io.BufferedIOBase | bytes
 
 class Error(Exception): ...
 
 class Encoder:
     def __init__(self) -> None: ...
-    def start(self, stream: io.RawIOBase | None = None) -> None: ...
+    def start(self, stream: EncoderStream = None, encoding: Encoding | None = None) -> None: ...
     def enter(self, nr: int, cls: int | None = None) -> None: ...
     def leave(self) -> None: ...
     def construct(self, nr: int, cls: int | None = None) -> Generator[None, Any, None]: ...
@@ -90,7 +84,7 @@ class Encoder:
 
 class Decoder:
     def __init__(self) -> None: ...
-    def start(self, stream: io.RawIOBase | bytes) -> None: ...
+    def start(self, stream: DecoderStream) -> None: ...
     def peek(self) -> Tag | None: ...
     def read(self, flags: ReadFlags = ...) -> tuple[Tag | None, Any]: ...
     def eof(self) -> bool: ...