From a20bcfc147c6d4f5f15982ef7e270b4e8a4d5322 Mon Sep 17 00:00:00 2001 From: mhostetter Date: Fri, 19 Aug 2022 13:45:15 -0400 Subject: [PATCH] Clean up `galois.typing` namespace --- galois/_domains/_array.py | 2 +- galois/_domains/_typing.py | 187 +++++++++++++++++++++++++++++++ galois/_polys/_typing.py | 50 +++++++++ galois/typing.py | 222 +------------------------------------ 4 files changed, 241 insertions(+), 220 deletions(-) create mode 100644 galois/_domains/_typing.py create mode 100644 galois/_polys/_typing.py diff --git a/galois/_domains/_array.py b/galois/_domains/_array.py index 8654b8c28..e875d5512 100644 --- a/galois/_domains/_array.py +++ b/galois/_domains/_array.py @@ -12,12 +12,12 @@ import numpy as np from .._overrides import set_module, SPHINX_BUILD -from ..typing import ElementLike, IterableLike, ArrayLike, ShapeLike, DTypeLike from ._function import FunctionMixin from ._linalg import LinalgFunctionMixin from ._lookup import UFuncMixin from ._meta import ArrayMeta +from ._typing import ElementLike, IterableLike, ArrayLike, ShapeLike, DTypeLike __all__ = ["Array"] diff --git a/galois/_domains/_typing.py b/galois/_domains/_typing.py new file mode 100644 index 000000000..887716806 --- /dev/null +++ b/galois/_domains/_typing.py @@ -0,0 +1,187 @@ +""" +A module containing type hints for the array-related objects. +""" +from __future__ import annotations + +from typing import Sequence, Union, TYPE_CHECKING + +import numpy as np + +# Obtain forward references +if TYPE_CHECKING: + from ._array import Array + +__all__ = ["ElementLike", "IterableLike", "ArrayLike", "ShapeLike", "DTypeLike"] + + +ElementLike = Union[int, str, "Array"] +""" +A :obj:`~typing.Union` representing objects that can be coerced into a Galois field element. + +:group: arrays + +Scalars are 0-D :obj:`~galois.Array` objects. + +.. rubric:: Union + +- :obj:`int`: A finite field element in its :ref:`integer representation `. + + .. ipython:: python + + GF = galois.GF(3**5) + GF(17) + +- :obj:`str`: A finite field element in its :ref:`polynomial representation `. Many string conventions are + accepted, including: with/without `*`, with/without spaces, `^` or `**`, any indeterminate variable, increasing/decreasing + degrees, etc. Or any combination of the above. + + .. ipython:: python + + GF("x^2 + 2x + 2") + # Add explicit * for multiplication + GF("x^2 + 2*x + 2") + # No spaces + GF("x^2+2x+2") + # ** instead of ^ + GF("x**2 + 2x + 2") + # Different indeterminate + GF("α^2 + 2α + 2") + # Ascending degrees + GF("2 + 2x + x^2") + +- :obj:`~galois.Array`: A previously-created scalar :obj:`~galois.Array` object. No coercion is necessary. + +.. rubric:: Alias +""" + + +IterableLike = Union[Sequence[ElementLike], Sequence["IterableLike"]] +""" +A :obj:`~typing.Union` representing iterable objects that can be coerced into a Galois field array. + +:group: arrays + +.. rubric:: Union + +- :obj:`~typing.Sequence` [ :obj:`~galois.typing.ElementLike` ]: An iterable of elements. + + .. ipython:: python + + GF = galois.GF(3**5) + GF([17, 4]) + # Mix and match integers and strings + GF([17, "x + 1"]) + +- :obj:`~typing.Sequence` [ :obj:`~galois.typing.IterableLike` ]: A recursive iterable of iterables of elements. + + .. ipython:: python + + GF = galois.GF(3**5) + GF([[17, 4], [148, 205]]) + # Mix and match integers and strings + GF([["x^2 + 2x + 2", 4], ["x^4 + 2x^3 + x^2 + x + 1", 205]]) + +.. rubric:: Alias +""" + + +ArrayLike = Union[IterableLike, np.ndarray, "Array"] +""" +A :obj:`~typing.Union` representing objects that can be coerced into a Galois field array. + +:group: arrays + +.. rubric:: Union + +- :obj:`~galois.typing.IterableLike`: A recursive iterable of iterables of elements. + + .. ipython:: python + + GF = galois.GF(3**5) + GF([[17, 4], [148, 205]]) + # Mix and match integers and strings + GF([["x^2 + 2x + 2", 4], ["x^4 + 2x^3 + x^2 + x + 1", 205]]) + +- :obj:`~numpy.ndarray`: A NumPy array of integers, representing finite field elements in their :ref:`integer representation `. + + .. ipython:: python + + x = np.array([[17, 4], [148, 205]]); x + GF(x) + +- :obj:`~galois.Array`: A previously-created :obj:`~galois.Array` object. No coercion is necessary. + +.. rubric:: Alias +""" + + +ShapeLike = Union[int, Sequence[int]] +""" +A :obj:`~typing.Union` representing objects that can be coerced into a NumPy :obj:`~numpy.ndarray.shape` tuple. + +:group: arrays + +.. rubric:: Union + +- :obj:`int`: The size of a 1-D array. + + .. ipython:: python + + GF = galois.GF(3**5) + x = GF.Random(4); x + x.shape + +- :obj:`~typing.Sequence` [ :obj:`int` ]: An iterable of integer dimensions. Tuples or lists are allowed. An empty iterable, `()` or `[]`, + represents a 0-D array (scalar). + + .. ipython:: python + + x = GF.Random((2, 3)); x + x.shape + x = GF.Random([2, 3, 4]); x + x.shape + x = GF.Random(()); x + x.shape + +.. rubric:: Alias +""" + + +DTypeLike = Union[np.integer, int, str, object] +""" +A :obj:`~typing.Union` representing objects that can be coerced into a NumPy data type. + +:group: arrays + +.. rubric:: Union + +- :obj:`numpy.integer`: A fixed-width NumPy integer data type. + + .. ipython:: python + + GF = galois.GF(3**5) + x = GF.Random(4, dtype=np.uint16); x.dtype + x = GF.Random(4, dtype=np.int32); x.dtype + +- :obj:`int`: The system default integer. + + .. ipython:: python + + x = GF.Random(4, dtype=int); x.dtype + +- :obj:`str`: The string that can be coerced with :obj:`numpy.dtype`. + + .. ipython:: python + + x = GF.Random(4, dtype="uint16"); x.dtype + x = GF.Random(4, dtype="int32"); x.dtype + +- :obj:`object`: A Python object data type. This applies to non-compiled fields. + + .. ipython:: python + + GF = galois.GF(2**100) + x = GF.Random(4, dtype=object); x.dtype + +.. rubric:: Alias +""" diff --git a/galois/_polys/_typing.py b/galois/_polys/_typing.py new file mode 100644 index 000000000..b47d77aa2 --- /dev/null +++ b/galois/_polys/_typing.py @@ -0,0 +1,50 @@ +""" +A module containing type hints for the polynomial-related objects. +""" +from __future__ import annotations + +from typing import Union, TYPE_CHECKING + +from .._domains._typing import ArrayLike + +# Obtain forward references +if TYPE_CHECKING: + from .._polys._poly import Poly + +__all__ = ["PolyLike"] + + +PolyLike = Union[int, str, ArrayLike, "Poly"] +""" +A :obj:`~typing.Union` representing objects that can be coerced into a polynomial. + +:group: polys + +.. rubric:: Union + +- :obj:`int`: A polynomial in its integer representation, see :func:`~galois.Poly.Int`. The Galois field must be known from context. + + .. ipython:: python + + # Known from context + GF = galois.GF(3) + galois.Poly.Int(19, field=GF) + +- :obj:`str`: A polynomial in its string representation, see :func:`~galois.Poly.Str`. The Galois field must be known from context. + + .. ipython:: python + + galois.Poly.Str("2x^2 + 1", field=GF) + +- :obj:`~galois.typing.ArrayLike`: An array of polynomial coefficients in degree-descending order. If the coefficients are not + :obj:`~galois.Array`, then the Galois field must be known from context. + + .. ipython:: python + + galois.Poly([2, 0, 1], field=GF) + galois.Poly(GF([2, 0, 1])) + +- :obj:`~galois.Poly`: A previously-created :obj:`~galois.Poly` object. No coercion is necessary. + +.. rubric:: Alias +""" diff --git a/galois/typing.py b/galois/typing.py index 07624501d..707caf944 100644 --- a/galois/typing.py +++ b/galois/typing.py @@ -1,222 +1,6 @@ """ A public module containing type hints for the :obj:`galois` library. """ -from __future__ import annotations - -from typing import Sequence, Union, TYPE_CHECKING - -import numpy as np - -# Obtain forward references -if TYPE_CHECKING: - from ._domains._array import Array - from ._polys._poly import Poly - - -ElementLike = Union[int, str, "Array"] -""" -A :obj:`~typing.Union` representing objects that can be coerced into a Galois field element. - -:group: arrays - -Scalars are 0-D :obj:`~galois.Array` objects. - -.. rubric:: Union - -- :obj:`int`: A finite field element in its :ref:`integer representation `. - - .. ipython:: python - - GF = galois.GF(3**5) - GF(17) - -- :obj:`str`: A finite field element in its :ref:`polynomial representation `. Many string conventions are - accepted, including: with/without `*`, with/without spaces, `^` or `**`, any indeterminate variable, increasing/decreasing - degrees, etc. Or any combination of the above. - - .. ipython:: python - - GF("x^2 + 2x + 2") - # Add explicit * for multiplication - GF("x^2 + 2*x + 2") - # No spaces - GF("x^2+2x+2") - # ** instead of ^ - GF("x**2 + 2x + 2") - # Different indeterminate - GF("α^2 + 2α + 2") - # Ascending degrees - GF("2 + 2x + x^2") - -- :obj:`~galois.Array`: A previously-created scalar :obj:`~galois.Array` object. No coercion is necessary. - -.. rubric:: Alias -""" - - -IterableLike = Union[Sequence[ElementLike], Sequence["IterableLike"]] -""" -A :obj:`~typing.Union` representing iterable objects that can be coerced into a Galois field array. - -:group: arrays - -.. rubric:: Union - -- :obj:`~typing.Sequence` [ :obj:`~galois.typing.ElementLike` ]: An iterable of elements. - - .. ipython:: python - - GF = galois.GF(3**5) - GF([17, 4]) - # Mix and match integers and strings - GF([17, "x + 1"]) - -- :obj:`~typing.Sequence` [ :obj:`~galois.typing.IterableLike` ]: A recursive iterable of iterables of elements. - - .. ipython:: python - - GF = galois.GF(3**5) - GF([[17, 4], [148, 205]]) - # Mix and match integers and strings - GF([["x^2 + 2x + 2", 4], ["x^4 + 2x^3 + x^2 + x + 1", 205]]) - -.. rubric:: Alias -""" - - -ArrayLike = Union[IterableLike, np.ndarray, "Array"] -""" -A :obj:`~typing.Union` representing objects that can be coerced into a Galois field array. - -:group: arrays - -.. rubric:: Union - -- :obj:`~galois.typing.IterableLike`: A recursive iterable of iterables of elements. - - .. ipython:: python - - GF = galois.GF(3**5) - GF([[17, 4], [148, 205]]) - # Mix and match integers and strings - GF([["x^2 + 2x + 2", 4], ["x^4 + 2x^3 + x^2 + x + 1", 205]]) - -- :obj:`~numpy.ndarray`: A NumPy array of integers, representing finite field elements in their :ref:`integer representation `. - - .. ipython:: python - - x = np.array([[17, 4], [148, 205]]); x - GF(x) - -- :obj:`~galois.Array`: A previously-created :obj:`~galois.Array` object. No coercion is necessary. - -.. rubric:: Alias -""" - - -ShapeLike = Union[int, Sequence[int]] -""" -A :obj:`~typing.Union` representing objects that can be coerced into a NumPy :obj:`~numpy.ndarray.shape` tuple. - -:group: arrays - -.. rubric:: Union - -- :obj:`int`: The size of a 1-D array. - - .. ipython:: python - - GF = galois.GF(3**5) - x = GF.Random(4); x - x.shape - -- :obj:`~typing.Sequence` [ :obj:`int` ]: An iterable of integer dimensions. Tuples or lists are allowed. An empty iterable, `()` or `[]`, - represents a 0-D array (scalar). - - .. ipython:: python - - x = GF.Random((2, 3)); x - x.shape - x = GF.Random([2, 3, 4]); x - x.shape - x = GF.Random(()); x - x.shape - -.. rubric:: Alias -""" - - -DTypeLike = Union[np.integer, int, str, object] -""" -A :obj:`~typing.Union` representing objects that can be coerced into a NumPy data type. - -:group: arrays - -.. rubric:: Union - -- :obj:`numpy.integer`: A fixed-width NumPy integer data type. - - .. ipython:: python - - GF = galois.GF(3**5) - x = GF.Random(4, dtype=np.uint16); x.dtype - x = GF.Random(4, dtype=np.int32); x.dtype - -- :obj:`int`: The system default integer. - - .. ipython:: python - - x = GF.Random(4, dtype=int); x.dtype - -- :obj:`str`: The string that can be coerced with :obj:`numpy.dtype`. - - .. ipython:: python - - x = GF.Random(4, dtype="uint16"); x.dtype - x = GF.Random(4, dtype="int32"); x.dtype - -- :obj:`object`: A Python object data type. This applies to non-compiled fields. - - .. ipython:: python - - GF = galois.GF(2**100) - x = GF.Random(4, dtype=object); x.dtype - -.. rubric:: Alias -""" - - -PolyLike = Union[int, str, ArrayLike, "Poly"] -""" -A :obj:`~typing.Union` representing objects that can be coerced into a polynomial. - -:group: polys - -.. rubric:: Union - -- :obj:`int`: A polynomial in its integer representation, see :func:`~galois.Poly.Int`. The Galois field must be known from context. - - .. ipython:: python - - # Known from context - GF = galois.GF(3) - galois.Poly.Int(19, field=GF) - -- :obj:`str`: A polynomial in its string representation, see :func:`~galois.Poly.Str`. The Galois field must be known from context. - - .. ipython:: python - - galois.Poly.Str("2x^2 + 1", field=GF) - -- :obj:`~galois.typing.ArrayLike`: An array of polynomial coefficients in degree-descending order. If the coefficients are not - :obj:`~galois.Array`, then the Galois field must be known from context. - - .. ipython:: python - - galois.Poly([2, 0, 1], field=GF) - galois.Poly(GF([2, 0, 1])) - -- :obj:`~galois.Poly`: A previously-created :obj:`~galois.Poly` object. No coercion is necessary. - -.. rubric:: Alias -""" +# pylint: disable=wildcard-import,unused-wildcard-import +from ._domains._typing import * +from ._polys._typing import *