0.0.5 release (#3)

* Underscore instead of hyphen for publish in Makefile.

* Increment version.

* Prefer shorter codepoint values when escaping for RE2.

* More uniformity in tests for regex expressions.

* Parameters actually accept string chars when iterating a character range.

* Add regex making function.

* Formatting change to bash commands in readme to make it easier to copy.

* Improve readability in a few docstring examples when rendered to markdown.

* Considering test parameterization.
- Added `to_nfc` test.
- Avoiding lru_cache when evalutating enum (just build expression on script initialization to prevent slowness for now).
- Additional/improved edge cases in some tests.
- Added reserved regex expressions to constants.

* Including requirements-test.txt for convenience.

* Use full match in test instead of search.

* Short-term implementation adding ability to change default regex flavor at any point.

* Update readme.

* RE2 should only be required for testing.

* Move `default_flavor` from `regex_toolkit.utils` to `regex_tookit.base` and add test for changing the default.

* Readme clean up.

Author: yaphott

.gitignore

@@ -8,6 +8,7 @@
 !environment.yml
 !codecov.yml
 !requirements-doc.txt
+!requirements-test.txt
 
 !src/
 !src/*

Makefile

@@ -1,5 +1,5 @@
 PYTHON=python3
-APP_NAME=regex-toolkit
+APP_NAME=regex_toolkit
 
 install:
 	${PYTHON} -m pip install .

README.md

@@ -36,7 +36,7 @@ Most stable version from [**PyPi**](https://pypi.org/project/regex-toolkit/):
 [![PyPI - License](https://img.shields.io/pypi/l/regex-toolkit?style=flat-square)](https://pypi.org/project/regex-toolkit/)
 
 ```bash
-$ python3 -m pip install regex-toolkit
+python3 -m pip install regex-toolkit
 ```
 
 Development version from [**GitHub**](https://github.com/Phosmic/regex-toolkit):
@@ -48,26 +48,49 @@ Development version from [**GitHub**](https://github.com/Phosmic/regex-toolkit):
 
 
 ```bash
-$ git clone git+https://github.com/Phosmic/regex-toolkit.git
-$ cd regex-toolkit
-$ python3 -m pip install -e .
+git clone git+https://github.com/Phosmic/regex-toolkit.git
+cd regex-toolkit
+python3 -m pip install -e .
 ```
 
 ---
 
 ## Usage
 
-Import packages:
+To harness the toolkit's capabilities, you should import the necessary packages:
 
 ```python
 import re
 # and/or
 import re2
+import regex_toolkit as rtk
 ```
 
-```python
-import regex_toolkit
-```
+### Why Use `regex_toolkit`?
+
+Regex definitions vary across languages and versions.
+By using the toolkit, you can achieve a more consistent and comprehensive representation of unicode support.
+It is especially useful to supplement base unicode sets with the latest definitions from other languages and standards.
+
+### RE2 Overview
+
+RE2 focuses on safely processing regular expressions, particularly from untrusted inputs.
+It ensures both linear match time and efficient memory usage.
+Although it might not always surpass other engines in speed, it intentionally omits features that depend solely on backtracking, like backreferences and look-around assertions.
+
+A brief rundown of RE2 terminology:
+
+- **BitState**: An execution engine that uses backtracking search.
+- **bytecode**: The set of instructions that form an automaton.
+- **DFA**: The engine for Deterministic Finite Automaton searches.
+- **NFA**: Implements the Nondeterministic Finite Automaton search method.
+- **OnePass**: A one-pass search execution engine.
+- **pattern**: The textual form of a regex.
+- **Prog**: The compiled version of a regex.
+- **Regexp**: The parsed version of a regex.
+- **Rune**: A character in terms of encoding, essentially a code point.
+
+For an in-depth exploration, please refer to the [RE2 documentation](https://github.com/google/re2/wiki/Glossary).
 
 ---
 
@@ -77,6 +100,39 @@ import regex_toolkit
 
 # `regex_toolkit.utils`
 
+<a id="regex_toolkit.utils.resolve_flavor"></a>
+
+#### `resolve_flavor`
+
+```python
+def resolve_flavor(potential_flavor: int | RegexFlavor | None) -> RegexFlavor
+```
+
+Resolve a regex flavor.
+
+If the flavor is an integer, it is validated and returned.
+If the flavor is a RegexFlavor, it is returned.
+If the flavor is None, the default flavor is returned. To change the default flavor, set `default_flavor`.
+
+```python
+import regex_toolkit as rtk
+
+rtk.base.default_flavor = 2
+assert rtk.utils.resolve_flavor(None) == rtk.enums.RegexFlavor.RE2
+```
+
+**Arguments**:
+
+- `potential_flavor` _int | RegexFlavor | None_ - Potential regex flavor.
+
+**Returns**:
+
+- _RegexFlavor_ - Resolved regex flavor.
+
+**Raises**:
+
+- `ValueError` - Invalid regex flavor.
+
 <a id="regex_toolkit.utils.iter_sort_by_len"></a>
 
 #### `iter_sort_by_len`
@@ -134,8 +190,8 @@ The codepoint is always 8 characters long (zero-padded).
 **Example**:
 
 ```python
-# Output: '00000061'
 ord_to_cpoint(97)
+# Output: '00000061'
 ```
 
 **Arguments**:
@@ -177,8 +233,8 @@ Character to character codepoint.
 **Example**:
 
 ```python
-# Output: '00000061'
 char_to_cpoint("a")
+# Output: '00000061'
 ```
 
 **Arguments**:
@@ -201,6 +257,13 @@ Normalize a Unicode string to NFC form C.
 
 Form C favors the use of a fully combined character.
 
+**Example**:
+
+```python
+to_nfc("e\\u0301") == "é"
+# Output: True
+```
+
 **Arguments**:
 
 - `text` _str_ - String to normalize.
@@ -214,39 +277,59 @@ Form C favors the use of a fully combined character.
 #### `iter_char_range`
 
 ```python
-def iter_char_range(first_cpoint: int,
-                    last_cpoint: int) -> Generator[str, None, None]
+def iter_char_range(first_char: str,
+                    last_char: str) -> Generator[str, None, None]
 ```
 
-Iterate all characters within a range of codepoints (inclusive).
+Iterate all characters within a range of characters (inclusive).
+
+**Example**:
+
+```python
+char_range("a", "c")
+# Output: ('a', 'b', 'c')
+
+char_range("c", "a")
+# Output: ('c', 'b', 'a')
+```
 
 **Arguments**:
 
-- `first_cpoint` _int_ - Starting (first) codepoint.
-- `last_cpoint` _int_ - Ending (last) codepoint.
+- `first_char` _str_ - Starting (first) character.
+- `last_char` _str_ - Ending (last) character.
 
 **Yields**:
 
-- _str_ - Characters within a range of codepoints.
+- _str_ - Characters within a range of characters.
 
 <a id="regex_toolkit.utils.char_range"></a>
 
 #### `char_range`
 
 ```python
-def char_range(first_cpoint: int, last_cpoint: int) -> tuple[str, ...]
+def char_range(first_char: str, last_char: str) -> tuple[str, ...]
 ```
 
-Tuple of all characters within a range of codepoints (inclusive).
+Tuple of all characters within a range of characters (inclusive).
+
+**Example**:
+
+```python
+char_range("a", "d")
+# Output: ('a', 'b', 'c', 'd')
+
+char_range("d", "a")
+# Output: ('d', 'c', 'b', 'a')
+```
 
 **Arguments**:
 
-- `first_cpoint` _int_ - Starting (first) codepoint.
-- `last_cpoint` _int_ - Ending (last) codepoint.
+- `first_char` _str_ - Starting (first) character.
+- `last_char` _str_ - Ending (last) character.
 
 **Returns**:
 
-- _tuple[str, ...]_ - Characters within a range of codepoints.
+- _tuple[str, ...]_ - Characters within a range of characters.
 
 <a id="regex_toolkit.utils.mask_span"></a>
 
@@ -303,15 +386,15 @@ Todo: Add support for overlapping (and unordered?) spans.
 #### `escape`
 
 ```python
-def escape(char: str, flavor: int = 1) -> str
+def escape(char: str, flavor: int | None = None) -> str
 ```
 
 Create a regex expression that exactly matches a character.
 
 **Arguments**:
 
 - `char` _str_ - Character to match.
-- `flavor` _int, optional_ - Regex flavor (1 for RE, 2 for RE2). Defaults to 1.
+- `flavor` _int | None, optional_ - Regex flavor (1 for RE, 2 for RE2). Defaults to None.
 
 **Returns**:
 
@@ -326,15 +409,15 @@ Create a regex expression that exactly matches a character.
 #### `string_as_exp`
 
 ```python
-def string_as_exp(text: str, flavor: int = 1) -> str
+def string_as_exp(text: str, flavor: int | None = None) -> str
 ```
 
 Create a regex expression that exactly matches a string.
 
 **Arguments**:
 
 - `text` _str_ - String to match.
-- `flavor` _int, optional_ - Regex flavor (1 for RE, 2 for RE2). Defaults to 1.
+- `flavor` _int | None, optional_ - Regex flavor (1 for RE, 2 for RE2). Defaults to None.
 
 **Returns**:
 
@@ -349,15 +432,15 @@ Create a regex expression that exactly matches a string.
 #### `strings_as_exp`
 
 ```python
-def strings_as_exp(texts: Iterable[str], flavor: int = 1) -> str
+def strings_as_exp(texts: Iterable[str], flavor: int | None = None) -> str
 ```
 
 Create a regex expression that exactly matches any one string.
 
 **Arguments**:
 
 - `texts` _Iterable[str]_ - Strings to match.
-- `flavor` _int, optional_ - Regex flavor (1 for RE, 2 for RE2). Defaults to 1.
+- `flavor` _int | None, optional_ - Regex flavor (1 for RE, 2 for RE2). Defaults to None.
 
 **Returns**:
 
@@ -367,6 +450,39 @@ Create a regex expression that exactly matches any one string.
 
 - `ValueError` - Invalid regex flavor.
 
+<a id="regex_toolkit.base.make_exp"></a>
+
+#### `make_exp`
+
+```python
+def make_exp(chars: Iterable[str], flavor: int | None = None) -> str
+```
+
+Create a regex expression that exactly matches a list of characters.
+
+The characters are sorted and grouped into ranges where possible.
+The expression is not anchored, so it can be used as part of a larger expression.
+
+**Example**:
+
+```python
+exp = "[" + make_exp(["a", "b", "c", "z", "y", "x"]) + "]"
+# Output: '[a-cx-z]'
+```
+
+**Arguments**:
+
+- `chars` _Iterable[str]_ - Characters to match.
+- `flavor` _int | None, optional_ - Regex flavor (1 for RE, 2 for RE2). Defaults to None.
+
+**Returns**:
+
+- _str_ - Expression that exactly matches the original characters.
+
+**Raises**:
+
+- `ValueError` - Invalid regex flavor.
+
 <a id="regex_toolkit.enums"></a>
 
 # `regex_toolkit.enums`

ci/deps/actions-310.yml

@@ -8,8 +8,5 @@ dependencies:
   - pytest>=7.0.0
   - pytest-cov
   - pytest-xdist>=2.2.0
-  # - pytest-asyncio>=0.17
-
-  # Required dependencies
   - pip:
     - google-re2>=1.0

ci/deps/actions-311.yml

@@ -8,8 +8,5 @@ dependencies:
   - pytest>=7.0.0
   - pytest-cov
   - pytest-xdist>=2.2.0
-  # - pytest-asyncio>=0.17
-
-  # Required dependencies
   - pip:
     - google-re2>=1.0

docs/templates/install.md.jinja

@@ -5,7 +5,7 @@ Most stable version from [**PyPi**](https://pypi.org/project/{{ pypi.name }}/):
 [![PyPI - License](https://img.shields.io/pypi/l/{{ pypi.name }}?style=flat-square)](https://pypi.org/project/{{ pypi.name }}/)
 
 ```bash
-$ python3 -m pip install {{ pypi.name }}
+python3 -m pip install {{ pypi.name }}
 ```
 
 Development version from [**GitHub**](https://github.com/{{ repo.owner }}/{{ repo.name }}):
@@ -21,7 +21,7 @@ Development version from [**GitHub**](https://github.com/{{ repo.owner }}/{{ rep
 {% endif %}
 
 ```bash
-$ git clone git+https://github.com/{{ repo.owner }}/{{ repo.name }}.git
-$ cd {{ repo.name }}
-$ python3 -m pip install -e .
+git clone git+https://github.com/{{ repo.owner }}/{{ repo.name }}.git
+cd {{ repo.name }}
+python3 -m pip install -e .
 ```

docs/templates/usage.md.jinja

@@ -1,11 +1,34 @@
-Import packages:
+To harness the toolkit's capabilities, you should import the necessary packages:
 
 ```python
 import re
 # and/or
 import re2
+import regex_toolkit as rtk
 ```
 
-```python
-import regex_toolkit
-```
+### Why Use `regex_toolkit`?
+
+Regex definitions vary across languages and versions.
+By using the toolkit, you can achieve a more consistent and comprehensive representation of unicode support.
+It is especially useful to supplement base unicode sets with the latest definitions from other languages and standards.
+
+### RE2 Overview
+
+RE2 focuses on safely processing regular expressions, particularly from untrusted inputs.
+It ensures both linear match time and efficient memory usage.
+Although it might not always surpass other engines in speed, it intentionally omits features that depend solely on backtracking, like backreferences and look-around assertions.
+
+A brief rundown of RE2 terminology:
+
+- **BitState**: An execution engine that uses backtracking search.
+- **bytecode**: The set of instructions that form an automaton.
+- **DFA**: The engine for Deterministic Finite Automaton searches.
+- **NFA**: Implements the Nondeterministic Finite Automaton search method.
+- **OnePass**: A one-pass search execution engine.
+- **pattern**: The textual form of a regex.
+- **Prog**: The compiled version of a regex.
+- **Regexp**: The parsed version of a regex.
+- **Rune**: A character in terms of encoding, essentially a code point.
+
+For an in-depth exploration, please refer to the [RE2 documentation](https://github.com/google/re2/wiki/Glossary).