bump to v2.0.0

- Split pregex package into "pregex.core" and "pregex.meta". All previous modules were moved to "pregex.core", while a new module "essentials.py" was added to "pregex.meta". - Greatly improved documentation page. - Added classes "pregex.core.assertions.[Not]EnclosedBy". - Added "Pregex.print_pattern()" method just for printing the pattern. - Added "Pregex.purge()" static method for clearing the regex cache. - Added "__quantifiable" field and "_is_quantifiable" method. - All match-like methods are now able to receive a path to a text file to extract text from in order to look for matches, via the "is_path" parameter. - "Pregex.__infer_type" now also infers whether pattern is quantifiable or not, and returns said result along with the pattern's type.
manoss96 · Aug 22, 2022 · 63f36ea · 63f36ea
1 parent 0edc98f
commit 63f36ea
Show file tree

Hide file tree

Showing 40 changed files with 2,527 additions and 620 deletions.
diff --git a/README.md b/README.md
@@ -13,7 +13,8 @@ This is where PRegEx comes in! PRegEx, which stands for Programmable Regular Exp
 2. Adds modularity to building RegEx patterns, as one can easily break down a complex pattern into simpler sub-patterns which can then be combined together.
 3. No longer having to escape meta characters such as "." and "*" as this is handled internally by PRegEx!
 4. Acts as a higher-level API on top of Python's built-in "re" module, providing access to its core functionality while saving you the trouble of having to deal with "re.Match" instances.
-5. No matter how complex the abstraction, it's always just a pure RegEx pattern that sits underneath which you can fetch and use any way you like!
+
+And remember, no matter how complex the abstraction, it's always just a pure RegEx pattern that sits underneath which you can fetch and use any way you like!
 
 
 <!-- Installation -->
@@ -32,11 +33,11 @@ pip install pregex
 In PRegEx, everything is a Programmable Regular Expression, or "Pregex" for short. This makes it easy for simple Pregex instances to be combined into more complex ones! Within the code snippet below, we construct a Pregex instance that will match any URL that ends with either ".com" or ".org" as well as any IP address for which a 4-digit port number is specified. Furthermore, in the case of a URL, we would like for its domain name to be separately captured as well.
 
 ```python
-from pregex.classes import AnyLetter, AnyDigit, AnyFrom
-from pregex.quantifiers import Optional, AtLeastAtMost
-from pregex.operators import Either
-from pregex.groups import Capture
-from pregex.pre import Pregex
+from pregex.core.classes import AnyLetter, AnyDigit, AnyFrom
+from pregex.core.quantifiers import Optional, AtLeastAtMost
+from pregex.core.operators import Either
+from pregex.core.groups import Capture
+from pregex.core.pre import Pregex
 
 # Define main sub-patterns.
 http_protocol = Optional("http" + Optional('s') + "://")
@@ -77,7 +78,7 @@ This is the pattern that we just built. Yikes!
 
 Besides from having access to its underlying pattern, we can use a Pregex instance to find matches within a piece of text. Consider for example the following string:
 ```python
-text = "text--192.168.1.1:8000--text--http://www.wikipedia.orghttps://youtube.com--text"
+text = "text--192.168.1.1:8000--text--http://www.wikipedia.org--text--https://youtube.com--text"
 ```
 By invoking the instance's "get_matches" method, we are able to scan the above string for any possible matches:
 ```python
@@ -97,13 +98,34 @@ As expected, there were only two captured groups since the first match is not a
 ```python
 [(None,), ('wikipedia',), ('youtube',)]
 ```
-You can learn more about how PRegEx works by visiting the [PRegEx Documentation Page][docs-url].
 
+Finally, you might have noticed that we built our pattern by utilizing
+various classes that were imported from modules under *pregex.core*. These
+modules contain classes through which the RegEx syntax is essentially replaced.
+However, PRegEx includes another set of modules, namely those under subpackage
+*pregex.meta*, whose classes that build upon those from *pregex.core* in order
+to provide higher-level patterns that are a bit more difficult to construct!
+
+```python
+
+from pregex.core.pre import Pregex
+from pregex.core.classes import AnyDigit
+from pregex.core.operators import Either
+from pregex.meta.essentials import HttpUrl, IPv4
 
-<!-- What to expect next? -->
-## What to expect next?
+port_number = 4 * AnyDigit()
+
+pre: Pregex = Either(
+    HttpUrl(capture_domain=True),
+    IPv4() + ":" + port_number
+)
+```
+
+By using classes found within the *pregex.meta* subpackage, we were able to
+construct more or less the same pattern as before only much more easily!
+
+You can learn more about how PRegEx works by visiting the [PRegEx Documentation Page][docs-url].
 
-Currently, the pregex package's core modules are still being built. In the near future, more modules will follow that will rely upon the package's core modules in order to provide abstractions for even more complex RegEx patterns!
 
 <!-- MARKDOWN LINKS & IMAGES -->
 [python-shield]: https://img.shields.io/badge/python-3.9-blue

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1 +1 @@
-pregex==1.5.4
+pregex==2.0.0
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,7 +22,7 @@
 author = 'Manos Stoumpos'
 
 # The full version, including alpha/beta/rc tags
-release = '1.5.4'
+release = '2.0.0'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/docstring/modules.rst b/docs/source/docstring/modules.rst
diff --git a/docs/source/docstring/pregex.rst b/docs/source/docstring/pregex.rst
diff --git a/docs/source/documentation/importing-practices.rst b/docs/source/documentation/importing-practices.rst
@@ -0,0 +1,42 @@
+#######################
+Importing Practices
+#######################
+
+Due to the relatively large number of modules contained within pregex,
+having to import each class individually can quickly become extremely annoying.
+For this reason, it is suggested that one handles their imports by
+including the following statements at the top of their Python script:
+
+* ``from pregex.core import *`` - Imports all core modules by using short aliases.
+  More specifically:
+
+  * Module :py:mod:`pregex.core.assertions` is imported as ``asr``
+  * Module :py:mod:`pregex.core.classes` is imported as ``cl``
+  * Module :py:mod:`pregex.core.groups` is imported as ``gr``
+  * Module :py:mod:`pregex.core.operators` is imported as ``op``
+  * Module :py:mod:`pregex.core.quantifiers` is imported as ``qu``
+  * Module :py:mod:`pregex.core.tokens` is imported as ``tk``
+  * Classes :class:`pregex.core.pre.Pregex` and :class:`pregex.core.pre.Empty` are imported as is.
+
+  Take a look at the example below to better understand how this works:
+
+  .. code-block:: python
+
+	from pregex.core import *
+
+	pre = op.Either("Hello", "Bye") + " World" + qu.Optional("!")
+
+	print(pre.get_pattern()) # This prints "(?:Hello|Bye) World!?"
+
+  It is recommended that you follow this practice as besides the fact that
+  it saves you the trouble of having to import from each module separately,
+  it also ensures that you are aware of the module that each class belongs in,
+  which in turn reveals a lot in regards to the class's functionality and how
+  it can be used.
+
+* ``from pregex.meta import *`` - Directly imports every class defined within any
+  one of the *meta* modules.
+
+
+Finally, one is also able to replace both of the above import statements
+with a single statement, namely ``from pregex import *``.
diff --git a/docs/source/documentation/modules/core/assertions.rst b/docs/source/documentation/modules/core/assertions.rst
@@ -0,0 +1,6 @@
+***********************
+pregex.core.assertions
+***********************
+.. automodule:: pregex.core.assertions
+   :members:
+   :undoc-members:
diff --git a/docs/source/documentation/modules/core/classes.rst b/docs/source/documentation/modules/core/classes.rst
@@ -0,0 +1,7 @@
+
+*********************
+pregex.core.classes
+*********************
+.. automodule:: pregex.core.classes
+   :members:
+   :undoc-members:
diff --git a/docs/source/documentation/modules/core/groups.rst b/docs/source/documentation/modules/core/groups.rst
@@ -0,0 +1,6 @@
+*********************
+pregex.core.groups
+*********************
+.. automodule:: pregex.core.groups
+   :members:
+   :undoc-members:
diff --git a/docs/source/documentation/modules/core/operators.rst b/docs/source/documentation/modules/core/operators.rst
@@ -0,0 +1,6 @@
+*********************
+pregex.core.operators
+*********************
+.. automodule:: pregex.core.operators
+   :members:
+   :undoc-members:
diff --git a/docs/source/documentation/modules/core/pre.rst b/docs/source/documentation/modules/core/pre.rst
@@ -0,0 +1,6 @@
+*********************
+pregex.core.pre
+*********************
+.. automodule:: pregex.core.pre
+   :members:
+   :undoc-members:
diff --git a/docs/source/documentation/modules/core/quantifiers.rst b/docs/source/documentation/modules/core/quantifiers.rst
@@ -0,0 +1,6 @@
+*************************
+pregex.core.quantifiers
+*************************
+.. automodule:: pregex.core.quantifiers
+   :members:
+   :undoc-members:
diff --git a/docs/source/documentation/modules/core/tokens.rst b/docs/source/documentation/modules/core/tokens.rst
@@ -0,0 +1,6 @@
+*********************
+pregex.core.tokens
+*********************
+.. automodule:: pregex.core.tokens
+   :members:
+   :undoc-members:
diff --git a/docs/source/documentation/modules/meta/essentials.rst b/docs/source/documentation/modules/meta/essentials.rst
@@ -0,0 +1,6 @@
+***********************
+pregex.meta.essentials
+***********************
+.. automodule:: pregex.meta.essentials
+   :members:
+   :undoc-members: