document new stuff

Author: ArachnidAbby

comprehensiveconfig/__init__.py

@@ -4,6 +4,7 @@
 
 from . import configio
 from . import spec
+from . import validators
 from .json import JsonWriter
 from .toml import TomlWriter
 
@@ -147,6 +148,7 @@ def reset_global(cls):
     "_ConfigSpecMeta",
     "_ConfigSpecABCMeta",
     "spec",
+    "validators",
     "configio",
     "JsonWriter",
     "TomlWriter",

comprehensiveconfig/validators.py

@@ -2,8 +2,9 @@
 
 import sys
 
+# unix
 NULL_BYTE = "\x00"
-
+# windows
 DEVICE_PATH_PREFIX = "\\\\?\\"
 DEVICE_PATH_NORMALIZED_PREFIX = "\\\\.\\"
 BANNED_WINDOWS_NAMES = (
@@ -36,10 +37,7 @@
 
 def validate_path_unix(path: str) -> bool:
     """Takes in a str filepath and validates whether or not it is valid on unix/linux"""
-    if NULL_BYTE in path:  # only invalid character
-        return False
-
-    return True
+    return NULL_BYTE not in path
 
 
 def validate_path_windows(path: str) -> bool:
@@ -109,3 +107,11 @@ def validate_path_sys_aware(path: str) -> bool:
         return validate_path_windows(path)
     else:
         return validate_path_unix(path)
+
+
+__all__ = [
+    "validate_path_unix",
+    "validate_path_windows",
+    "validate_path_agnostic",
+    "validate_path_sys_aware",
+]

docs/source/fields.rst

@@ -120,6 +120,9 @@ Module
     .. py:attribute:: _holds
         :type: str
 
+    .. py:attribute:: _regex_pattern
+        :type: str
+
 
 .. py:class:: comprehensiveconfig.spec.List[T](default_value: list[T] = [], /, inner_type: AnyConfigField | None = None, **kwargs)
 
@@ -133,6 +136,57 @@ Module
 
         Might require manual annotation if your default value remains an empty list
 
+.. py:class:: comprehensiveconfig.spec.PathField(default_value: Path | str | _NoDefaultValueT = NoDefaultValue, /, path_type: PathField.PathType = PathField.directory_or_file, path_validator: PathField.PathValidator = PathValidator.agnostic, **kwargs)
+
+    :param Path | str | _NoDefaultValueT default_value: The default for this field.
+    :param PathField.PathType path_type: Whether you want to only accept files, directories, or both
+    :param PathField.PathValidator path_validator: Determines how it should validate the path string.
+
+    .. py:attribute:: _holds
+        :type: Path
+
+    .. py:attribute:: _path_type
+        :type: PathField.PathType
+
+    .. py:attribute:: _path_validator
+        :type: PathField.PathValidator
+
+.. py:class:: comprehensiveconfig.spec.PathField.PathType
+
+        This is an enum representing the types of paths we would like to support in this field.
+
+        .. py:data:: directory
+
+            We only want paths to point to directories!
+
+        .. py:data:: file
+
+            We only want paths to point to files!
+
+        .. py:data:: directory_or_file
+
+            Disables specific checks for what the paths are pointing to.
+
+.. py:class:: comprehensiveconfig.spec.PathField.PathValidator
+
+        This is an enum representing the different path validators defined in :py:mod:`comprehensiveconfig.validators`
+
+        .. py:data:: windows
+
+            Paths should only be valid Windows paths.
+
+        .. py:data:: unix
+
+            Paths should only be valid Unix Paths
+
+        .. py:data:: agnostic
+
+            Checks for validity on Unix or Windows (only one needs to be valid).
+
+        .. py:data:: current_system
+
+            Uses the validator corresponding to the current current system.
+
 .. py:class:: comprehensiveconfig.spec.Table[K, V](default_value: dict[K, V] = {}, /, key_type: AnyConfigField | None = None, value_type: AnyConfigField | None = None, **kwargs)
 
     :param dict[K, V] default_value: The default value of the field. This always default to an empty dict (required for static type checking)

docs/source/globaltoc.rst

@@ -25,4 +25,5 @@
     :maxdepth: 2
     :caption: Utilities:
 
-    utilities.rst
+    utilities.rst
+    validators.rst

docs/source/index.rst

@@ -41,6 +41,7 @@ loading as well as complex validators for incoming configuration values.
     :caption: Utilities:
 
     utilities.rst
+    validators.rst
 
 Module
 ********

docs/source/validators.rst

@@ -0,0 +1,38 @@
+Validators
+===========
+
+This file primarily contains various validators used throughout the spec.
+
+.. py:currentmodule:: comprehensiveconfig.validators
+
+
+Module
+********
+
+.. py:function:: validate_path_unix(path: str) -> bool
+
+    This function takes a string path and validates whether or not it would be valid on a Unix system.
+    This is a simple check to see if the path contains a null byte (:code:`\x00`).
+
+    :param str path: The path as a :bold:`string`. Path objects do not work here!
+
+
+.. py:function:: validate_path_windows(path: str) -> bool
+
+    This function takes a string path and validates whether or not it would be valid on a windows system.
+    This is a muchmore complex function than the one for Unix systems.
+
+    :param str path: The path as a :bold:`string`. Path objects do not work here!
+
+
+.. py:function:: validate_path_agnostic(path: str) -> bool
+
+    This function checks if a path would be valid on Unix OR Windows. It first runs the check for Unix (its less expensive) before then checking for validity on Windows.
+
+    :param str path: The path as a :bold:`string`. Path objects do not work here!
+
+.. py:function:: validate_path_sys_aware(path: str) -> bool
+
+    Another path validator function but this one determines the system you are currently on before choosing which validator to use.
+
+    :param str path: The path as a :bold:`string`. Path objects do not work here!

readme.md

@@ -13,16 +13,19 @@ A simple configuration library that lets you create a pydantic-like model for yo
 - [x] Supports static type checking
 - [x] toml writer
 - [x] json writer
-- [x] Number Fields
-- [x] Text Fields (with regex filtering)
+- [x] Number fields
+- [x] Text fields (with regex filtering)
+- [x] File/Folder path fields (`PathField`)
+  - [x] Ability to change validator (unix/linux, windows, agnostic, and current system)
+  - [x] Validate for only files, folder, or accept both.
 - [x] List fields
 - [x] Table fields
 - [x] TableSpec (Model) fields
 - [x] Sections
 - [x] Include doc comments in Section
 - [x] auto loading
 - [x] initialize default config (with auto loader)
-- [ ] yaml writer
+- [N/a] yaml writer (This will likely be moved to a different library as an extension of comprehensiveconfig!)
 - [ ] Tests targetting mypy and other static type checkers to ensure EVERYTHING looks good across IDE's
 - [x] section list (via a Table field)
 - [x] Field type unions (overwriting normal union syntax)