turboenv 0.2.0a1__tar.gz

turboenv-0.2.0a1/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.3
+Name: turboenv
+Version: 0.2.0a1
+Summary: TurboEnv is a Python library that provides a simple and efficient way to manage environment variables in your applications. It allows you to easily load environment variables from .env files, access them in your code, and handle different environments (development, testing, production) with ease.
+Author: John Pendenque
+Author-email: John Pendenque <pendenquejohn@gmail.com>
+License: MIT
+Classifier: Development Status :: 1 - Planning
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: MacOS
+Requires-Dist: pydantic>=2.13.4
+Maintainer: John Pendenque
+Maintainer-email: John Pendenque <pendenquejohn@gmail.com>
+Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/Zadigo/turboenv/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Zadigo/turboenv/wiki
+Project-URL: Homepage, https://github.com/Zadigo/turboenv
+Project-URL: Repository, https://github.com/Zadigo/turboenv.git
+Description-Content-Type: text/markdown
+
+# Turbo Env
+
+TurboEnv is a Python library that provides a simple and efficient way to manage environment variables in your applications. It allows you to easily load environment variables from .env files, access them in your code, and handle different environments (development, testing, production) with ease.
+
+## Installation
+
+```Shell
+pip install turboenv
+```
+
+## Loading Environment variables
+
+## Automatic detection
+
+When `load_envs` is first called, it looks for any `.env` located in the absolute path of the file that is calling it. If it finds one, it loads the environment variables from that file in the `default` namespace.
+
+```python
+from turboenv import TurboEnv
+
+env = TurboEnv()
+env.load_envs()
+```
+
+You can also specify the path to the `.env` file and the namespace you want to load it into.
+
+```python
+from turboenv import TurboEnv
+
+env = TurboEnv()
+env.load_envs('path/to/.env')
+
+env.string('DB_USER')  # Accesses the DB_USER variable from the default namespace
+```
+
+## Accessing Environment Variables
+
+Once the environment variables are loaded, you can access them in multiple different manners including typecasting their values to a specific one:
+
+### Get method
+
+Tries to get the value of the environment variable with the given name. If the variable is not found, an `exceptions.MissingEnvVariableError` is raised.
+
+```python
+db_user = env.get("DB_USER")
+db_password = env.get("DB_PASSWORD")
+```
+
+### Boolean - Type Casting
+
+Returns the boolean value of the environment variable with the given name:
+
+```python
+db_password = env.boolean("USE_DB")
+```
+
+### String - Type Casting
+
+Returns the string value of the environment variable with the given name:
+
+```python
+db_password = env.string("DB_PASSWORD")
+```
+
+### Array - Type Casting
+
+Returns a list of strings by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_hosts = env.array("ALLOWED_HOSTS", cast=str)
+```
+
+### String List - Type Casting
+
+Returns a list of strings by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_hosts = env.str_list("ALLOWED_HOSTS")
+```
+
+### Integer List - Type Casting
+
+Returns a list of integers by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_ports = env.int_list("ALLOWED_PORTS")
+```
+
+### Domain List - Type Casting
+
+Returns a list of domain names by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_domains = env.domain_list("ALLOWED_DOMAINS")
+```
+
+### URL List - Type Casting
+
+Returns a list of URLs by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_urls = env.url_list("ALLOWED_URLS")
+```
+
+### Secret - Type Casting
+
+Returns the value of the environment variable with the given name, decoded from base64:
+
+```python
+db_password = env.secret("DB_PASSWORD")
+```
+
+### Path - Type Casting
+
+Returns a `Path` object representing the path specified by the environment variable with the given name:
+
+```python
+config_path = env.path("CONFIG_PATH")
+```
+
+> [!NOTE]
+> The secret value should already be encoded in base64 or this will raise an error.
+
+## Conditionals
+
+Conditionals are used to guarantee the integrity of your environment variables by checking if they meet certain conditions. 
+When the conditions are not met, an exception is raised.
+
+### Depends On
+
+Requires the presence of the specified environment variable in the environment.
+
+```python
+env.conditional("DB_USER").depends_on(values=["DB_PASSWORD"])
+```
+
+> [!CAUTION]
+> It does not check the actual values of the environment variables, only their presence.
+
+### To Be
+
+Requires the value of the environment variable to be equal to a specified value.
+
+```python
+env.conditional("DB_USER").to_be("admin")
+```
+
+### Not To Be
+
+Requires the value of the environment variable to not be equal to a specified value.
+
+```python
+env.conditional("DB_PASSWORD").not_to_be("password")
+```
+
+### To Exist
+
+Requires the environment variable to be present.
+
+> [!CAUTION]
+> This does not check if the value of the environment variable is empty or not, it only checks if it is present in the environment.
+
+```python
+env.conditional("DB_USER").to_exist()
+```
+
+### To Not Be Empty
+
+Requires the value of the environment variable to not be empty.
+
+```python
+env.conditional("DB_PASSWORD").to_not_be_empty()
+```
+
+### To Contain
+
+Requires the value of the environment variable to contain a specified substring.
+
+```python
+env.conditional("ALLOWED_HOSTS").to_contain("example.com")
+```
+
+### Path To Exist
+
+Requires the value of the environment variable to be a valid path that exists in the file system.
+
+```python
+env.conditional("CONFIG_PATH").path_to_exist()
+```
+
+# Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or find any bugs.
+
+
+To run the tests, use the following command:
+
+```bash
+pytest
+```
+
+# License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

turboenv-0.2.0a1/README.md

@@ -0,0 +1,203 @@
+# Turbo Env
+
+TurboEnv is a Python library that provides a simple and efficient way to manage environment variables in your applications. It allows you to easily load environment variables from .env files, access them in your code, and handle different environments (development, testing, production) with ease.
+
+## Installation
+
+```Shell
+pip install turboenv
+```
+
+## Loading Environment variables
+
+## Automatic detection
+
+When `load_envs` is first called, it looks for any `.env` located in the absolute path of the file that is calling it. If it finds one, it loads the environment variables from that file in the `default` namespace.
+
+```python
+from turboenv import TurboEnv
+
+env = TurboEnv()
+env.load_envs()
+```
+
+You can also specify the path to the `.env` file and the namespace you want to load it into.
+
+```python
+from turboenv import TurboEnv
+
+env = TurboEnv()
+env.load_envs('path/to/.env')
+
+env.string('DB_USER')  # Accesses the DB_USER variable from the default namespace
+```
+
+## Accessing Environment Variables
+
+Once the environment variables are loaded, you can access them in multiple different manners including typecasting their values to a specific one:
+
+### Get method
+
+Tries to get the value of the environment variable with the given name. If the variable is not found, an `exceptions.MissingEnvVariableError` is raised.
+
+```python
+db_user = env.get("DB_USER")
+db_password = env.get("DB_PASSWORD")
+```
+
+### Boolean - Type Casting
+
+Returns the boolean value of the environment variable with the given name:
+
+```python
+db_password = env.boolean("USE_DB")
+```
+
+### String - Type Casting
+
+Returns the string value of the environment variable with the given name:
+
+```python
+db_password = env.string("DB_PASSWORD")
+```
+
+### Array - Type Casting
+
+Returns a list of strings by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_hosts = env.array("ALLOWED_HOSTS", cast=str)
+```
+
+### String List - Type Casting
+
+Returns a list of strings by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_hosts = env.str_list("ALLOWED_HOSTS")
+```
+
+### Integer List - Type Casting
+
+Returns a list of integers by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_ports = env.int_list("ALLOWED_PORTS")
+```
+
+### Domain List - Type Casting
+
+Returns a list of domain names by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_domains = env.domain_list("ALLOWED_DOMAINS")
+```
+
+### URL List - Type Casting
+
+Returns a list of URLs by splitting the value of the environment variable with the given name using a specified separator (default is comma):
+
+```python
+allowed_urls = env.url_list("ALLOWED_URLS")
+```
+
+### Secret - Type Casting
+
+Returns the value of the environment variable with the given name, decoded from base64:
+
+```python
+db_password = env.secret("DB_PASSWORD")
+```
+
+### Path - Type Casting
+
+Returns a `Path` object representing the path specified by the environment variable with the given name:
+
+```python
+config_path = env.path("CONFIG_PATH")
+```
+
+> [!NOTE]
+> The secret value should already be encoded in base64 or this will raise an error.
+
+## Conditionals
+
+Conditionals are used to guarantee the integrity of your environment variables by checking if they meet certain conditions. 
+When the conditions are not met, an exception is raised.
+
+### Depends On
+
+Requires the presence of the specified environment variable in the environment.
+
+```python
+env.conditional("DB_USER").depends_on(values=["DB_PASSWORD"])
+```
+
+> [!CAUTION]
+> It does not check the actual values of the environment variables, only their presence.
+
+### To Be
+
+Requires the value of the environment variable to be equal to a specified value.
+
+```python
+env.conditional("DB_USER").to_be("admin")
+```
+
+### Not To Be
+
+Requires the value of the environment variable to not be equal to a specified value.
+
+```python
+env.conditional("DB_PASSWORD").not_to_be("password")
+```
+
+### To Exist
+
+Requires the environment variable to be present.
+
+> [!CAUTION]
+> This does not check if the value of the environment variable is empty or not, it only checks if it is present in the environment.
+
+```python
+env.conditional("DB_USER").to_exist()
+```
+
+### To Not Be Empty
+
+Requires the value of the environment variable to not be empty.
+
+```python
+env.conditional("DB_PASSWORD").to_not_be_empty()
+```
+
+### To Contain
+
+Requires the value of the environment variable to contain a specified substring.
+
+```python
+env.conditional("ALLOWED_HOSTS").to_contain("example.com")
+```
+
+### Path To Exist
+
+Requires the value of the environment variable to be a valid path that exists in the file system.
+
+```python
+env.conditional("CONFIG_PATH").path_to_exist()
+```
+
+# Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or find any bugs.
+
+
+To run the tests, use the following command:
+
+```bash
+pytest
+```
+
+# License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

turboenv-0.2.0a1/pyproject.toml

@@ -0,0 +1,118 @@
+[project]
+name = "turboenv"
+version = "0.2.0a1"
+description = "TurboEnv is a Python library that provides a simple and efficient way to manage environment variables in your applications. It allows you to easily load environment variables from .env files, access them in your code, and handle different environments (development, testing, production) with ease."
+readme = "README.md"
+requires-python = ">=3.13"
+license = {text = "MIT"}
+authors = [
+  {name = "John Pendenque", email = "pendenquejohn@gmail.com"},
+]
+maintainers = [
+  {name = "John Pendenque", email = "pendenquejohn@gmail.com"}
+]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Operating System :: POSIX",
+  "Operating System :: Unix",
+  "Operating System :: Microsoft :: Windows",
+  "Intended Audience :: Developers",
+  "Topic :: Internet",
+  "Topic :: Internet :: WWW/HTTP",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
+  "Natural Language :: English",
+  "Operating System :: Microsoft :: Windows :: Windows 11",
+  "Operating System :: MacOS"
+]
+dependencies = [
+    "pydantic>=2.13.4",
+]
+
+[dependency-groups]
+dev = [
+    "autopep8>=2.3.2",
+    "coverage>=7.14.1",
+    "django>=6.0.6",
+    "django-environ>=0.13.0",
+    "dotenv>=0.9.9",
+    "factory-boy>=3.3.3",
+    "fastapi[standard]>=0.136.3",
+    "pytest>=9.0.3",
+    "pytest-aio>=2.1.7",
+    "pytest-cov>=7.1.0",
+    "pytest-datafiles>=3.0.1",
+    "pytest-django>=4.12.0",
+    "pytest-env>=1.6.0",
+    "pytest-reportlog>=1.0.0",
+    "ruff>=0.15.16",
+]
+
+[project.urls]
+Homepage = "https://github.com/Zadigo/turboenv"
+Documentation = "https://github.com/Zadigo/turboenv/wiki"
+Repository = "https://github.com/Zadigo/turboenv.git"
+Changelog = "https://github.com/Zadigo/turboenv/blob/main/CHANGELOG.md"
+
+[tool.pyright]
+typeCheckingMode = "basic"
+reportMissingImports = true
+reportUntypedBaseClass = true
+
+[tool.pytest]
+testpaths = ["tests"]
+timeout="5000"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "api: marks tests as api tests",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+]
+
+[tool.pytest_env]
+env_files = [".env", ".env.test"]
+
+[tool.autopep8]
+max_line_length = 120
+in-place = true
+recursive = true
+aggressive = 3
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[build-system]
+requires = ["uv_build>=0.9,<0.10"]
+build-backend = "uv_build"
+
+[tool.coverage.run]
+omit = [
+    "manage.py",
+    "*/migrations/*",
+    "*/__init__.py",
+    "*/typings.py",
+    "conftest.py",
+    "tests/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+
+[tool.uv.build-backend]
+source-exclude = [
+    "**/tests/**",
+    "docs/**",
+    "*.log",
+    "**/.DS_Store",
+    "conftest.py",
+    "manage.py"
+]

turboenv-0.2.0a1/src/turboenv/__main__.py

@@ -0,0 +1,21 @@
+import argparse
+import os
+import pathlib
+
+if __name__ == '__main__':
+    argparser = argparse.ArgumentParser(description='TurboEnv: A tool for managing environment variables.')
+
+    argparser.add_argument(
+        '-l',
+        '--list-files',
+        action='store_true',
+        help='List all the files in the current directory that end with .env'
+    )
+
+    namespace = argparser.parse_args()
+
+    if namespace.list_files:
+        current_dir = pathlib.Path(os.getcwd())
+        files = current_dir.glob('*.env')
+        for file in files:
+            print(f'  * {file}')

turboenv-0.2.0a1/src/turboenv/exceptions.py

@@ -0,0 +1,22 @@
+from turboenv.typings import TypeAny
+
+
+class TurboEnvError(Exception):
+    message = "An error occurred in TurboEnv."
+
+class MissingEnvVariableError(TurboEnvError):
+    message = "The specified environment variable is missing: {values}"
+
+    def __init__(self, *values: str):
+        self.values = ', '.join(values)
+        message = self.message.format(values=self.values)
+        super().__init__(message)
+
+
+class ConditionalError(TurboEnvError):
+    message = "A conditional check failed: {details}"
+
+    def __init__(self, value: TypeAny | None, expected: TypeAny, condition: str):
+        self.details = f"Expected {value} {condition} {expected}"
+        message = self.message.format(details=self.details)
+        super().__init__(message)

turboenv-0.2.0a1/src/turboenv/main.py

@@ -0,0 +1,668 @@
+import base64
+import json as json_module
+import logging
+import os
+import pathlib
+import re
+from collections import OrderedDict
+from contextlib import contextmanager
+from typing import Callable, Generator, Self, Sequence
+from urllib.parse import urlparse
+
+from turboenv import exceptions
+from turboenv.typings import TypeAny, TypeCast
+
+logger = logging.getLogger(__name__)
+
+
+def expand(instance: 'TurboEnv', key: str) -> str | None:
+    """
+    Expands environment variables in the given string.
+
+    Example usage::
+
+        from turboenv import expand
+    
+        expanded_value = expand(instance, "USER")
+
+    Args:
+        instance (TurboEnv): The TurboEnv instance.
+        key (str): The key of the environment variable to expand.
+
+    Returns:
+        str | None: The string with environment variables expanded, or None if the value is not found.
+    """
+    value = instance._cache.get(key, None)
+    
+    if value is not None:
+        other_env = re.search(r'%(\w+)%', value)
+        if other_env:
+            env_var = other_env.group(1)
+            new_value = os.getenv(env_var, "")
+            new_env_value = value.replace(f"%{env_var}%", new_value)
+            instance._cache[key] = new_env_value
+            return new_env_value
+
+
+@contextmanager
+def _load_file(path: pathlib.Path, encoding: str = 'utf-8') -> Generator[list[str], None, None]:
+    with path.open(encoding=encoding) as f:
+        lines = f.readlines()
+        yield lines
+
+
+class Conditionals:
+    def __init__(self, instance: 'TurboEnv', name: str):
+        self.instance = instance
+        self._name = name
+
+    def value(self):
+        return self.instance._cache.get(self._name, None)
+
+    def depends_on(self, values: list[str] = []) -> Self:
+        """Blocks the execution of the code until the specified environment variables exist. 
+        If any of the specified environment variables do not exist, it raises an ExceptionGroup 
+        containing all the MissingEnvVariableError instances for the missing variables.
+
+        A typical use case for this method is when you have environment variables that depend on each other,
+        like in the case of a database URL that depends on the existence of a database host, port, username, and password.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+            
+            env = TurboEnv()
+            env.load_envs('.env')
+
+            # This will block until the environment variables DB_HOST, DB_PORT, DB_USER, and DB_PASSWORD exist
+            env.conditional('DATABASE_URL').depends_on(['DB_HOST', 'DB_PORT', 'DB_USER', 'DB_PASSWORD'])
+
+            env.string('DATABASE_URL')  # This will now work because the required environment variables exist
+
+        Args:
+            values (list[str]): A list of strings representing the names of the environment variables to check for existence.
+
+        Raises:
+            ExceptionGroup: If any of the specified environment variables do not exist, an ExceptionGroup is raised containing all the MissingEnvVariableError instances for the missing variables.
+        """
+        errors: list[exceptions.MissingEnvVariableError] = []
+        for name in values:
+            if not self.instance._exists(name):
+                errors.append(exceptions.MissingEnvVariableError(name))
+
+        if errors:
+            variables = ', '.join(values)
+            raise ExceptionGroup(
+                f"{self._name} is missing one or many dependencies: {variables}", errors)
+
+        return self
+
+    def to_be(self, expected: TypeAny) -> Self:
+        """
+        Checks if the value of the environment variable is equal to the expected value.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+            
+            conditional = env.conditional("DATABASE_URL")
+            conditional.to_be("postgres://user:password@localhost:5432/dbname")
+
+        Args:
+            expected (T): The expected value to compare against.
+
+        Raises:
+            ConditionalError: If the value of the environment variable is not equal to the expected value.
+        """
+        value = self.value()
+        if value != expected:
+            raise exceptions.ConditionalError(value, expected, "to be")
+        return self
+
+    def not_to_be(self, expected: TypeAny) -> Self:
+        """
+        Checks if the value of the environment variable is not equal to the expected value.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+            
+            conditional = env.conditional("DATABASE_URL")
+            conditional.not_to_be("postgres://user:password@localhost:5432/dbname")
+
+        Args:
+            expected (T): The expected value to compare against.
+
+        Raises:
+            ConditionalError: If the value of the environment variable is equal to the expected value.
+        """
+        value = self.value()
+        if value == expected:
+            raise exceptions.ConditionalError(
+                value, expected, "not to be")
+        return self
+
+    def to_exist(self) -> Self:
+        """
+        Checks if the value of the environment variable exists (is not None).
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+            
+            conditional = env.conditional("DATABASE_URL")
+            conditional.to_exist()
+
+        Raises:
+            ConditionalError: If the value of the environment variable is None.
+        """
+        value = self.value()
+        if value is None:
+            raise exceptions.ConditionalError(value, None, "exist")
+        return self
+
+    def to_not_be_empty(self) -> Self:
+        """
+        Checks if the value of the environment variable is not empty.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+            
+            conditional = env.conditional("DATABASE_URL")
+            conditional.to_not_be_empty()
+
+        Raises:
+            ConditionalError: If the value of the environment variable is None or an empty string.
+        """
+        value = self.value()
+        if value is None or value == "":
+            raise exceptions.ConditionalError(value, None, "not be empty")
+        return self
+
+    def to_contain(self, expected: TypeAny) -> Self:
+        """
+        Checks if the value of the environment variable contains the expected value.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+            
+            conditional = env.conditional("DATABASE_URL")
+            conditional.to_contain(["postgres"])
+
+        Raises:
+            ConditionalError: If the value of the environment variable does not contain the expected value.
+            TypeError: If the value of the environment variable is not a list or a string.
+        """
+        value = self.value()
+        if not isinstance(value, (list, str)):
+            raise TypeError(
+                "Value must be a list or a string to use to_contain")
+
+        if str(expected) not in value:
+            raise exceptions.ConditionalError(value, expected, "contain")
+        return self
+
+    def path_to_exist(self) -> Self:
+        """
+        Checks if the value of the environment variable, interpreted as a file path, exists.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+            
+            conditional = env.conditional("DATABASE_PATH")
+            conditional.path_to_exist()
+
+        Raises:
+            ConditionalError: If the value of the environment variable is None.
+            TypeError: If the value of the environment variable is not a string or a pathlib.Path.
+            FileNotFoundError: If the path does not exist.
+        """
+        value = self.value()
+        if not isinstance(value, (str, pathlib.Path)):
+            raise TypeError(
+                "Value must be a string or a pathlib.Path to use path_to_exist")
+
+        value = self.value()
+        if value is None:
+            raise exceptions.ConditionalError(
+                self._name, None, "exist as a path")
+
+        path = pathlib.Path(value)
+        if not path.exists():
+            raise FileNotFoundError(
+                f"Path from env variable {self._name} does not exist")
+        return self
+
+
+class TurboEnv:
+    """A class for managing environment variables with support for 
+    loading from files, type casting, and conditional logic.
+
+    Example usage:
+
+        from main import TurboEnv
+
+        env = TurboEnv()
+        env.load_envs('.env')
+
+        debug_mode = env.boolean('DEBUG_MODE', default=False)
+        database_url = env.string('DATABASE_URL')
+        allowed_hosts = env.str_list('ALLOWED_HOSTS', default=[])
+
+    Variables can separated by namespaces using the `namespace` method. Variables that do not specify a namespace 
+    are loaded in the global namespace and are accessible directly from the main instance.
+
+        from main import TurboEnv
+
+        env = TurboEnv()
+        env.load_envs(('test', '.env'), ('prod', '.env.prod'))   
+
+        test_envs = env.namespace('test')
+        database_url = test_envs.str('URL')
+
+    Args:
+        fail_on_missing (bool): If True, raises a FileNotFoundError if any of the specified files do not exist. Defaults to False.
+        only (str): If specified, only loads environment variables that start with this prefix. Defaults to None.
+        skip_empty (bool): If True, skips empty lines in the environment files. Defaults to False.
+    """
+
+    _cache: OrderedDict[str, str] = OrderedDict()
+
+    def __init__(self, fail_on_missing: bool = False, skip_empty: bool = False):
+        self.fail_on_missing = fail_on_missing
+        self.skip_empty = skip_empty
+        self._files: set[pathlib.Path] = set()
+
+    def __call__(self, **defaults: str) -> "TurboEnv":
+        self._cache.update(defaults)
+        return self
+
+    def __repr__(self) -> str:
+        return f"TurboEnv(cache={len(self._cache)}, files={len(self._files)})"
+
+    @property
+    def has_files(self) -> bool:
+        return len(self._files) > 0
+
+    @classmethod
+    def new(cls, **envs: str) -> "TurboEnv":
+        instance = cls()
+        instance._cache.update(envs)
+        return instance
+
+    def _exists(self, name: str) -> bool:
+        """Checks if the specified environment variable exists in the cache.
+        Used for internal checks and conditional logic."""
+        return name in self._cache
+
+    def load_envs(self, *args: str):
+        """Loads environment variables from the specified files. 
+        If no files are specified, it defaults to loading from a 
+        file named `.env` in the current directory.
+
+        Args:
+            *args (str): A variable number of string arguments representing the file paths to load.
+
+        Raises:
+            FileNotFoundError: If `fail_on_missing` is set to True and any of the specified files do not exist.
+        """
+        if not args:
+            args = ('.env',)
+
+        # To avoid loading the same files multiple times, we can check if the files 
+        # have already been loaded by looking for a specific environment variable that we set 
+        # after loading the files -; this is for performance optimization
+        load_completed = os.environ.get('TURBO_ENV_LOADED_FILES', 'False') == 'True'
+        if load_completed:
+            # FIXME: For whatever reason, in Django when the settings
+            # module is reloaded  the environment variables from the
+            # file are lost and only the system environment variables are preserved.
+            #  This is a workaround to reload the environment variables from 
+            # the system environment in case they are lost after the initial load.
+            for key, value in os.environ.items():
+                self._cache[key] = value
+            return
+
+        for filename in args:
+            path = pathlib.Path(filename)
+
+            if self.fail_on_missing:
+                if not path.exists():
+                    raise FileNotFoundError(f"File {filename} does not exist")
+
+            if path.exists():
+                self._files.add(path)
+
+                with _load_file(path) as lines:
+                    for line in lines:
+                        if line == "\n":
+                            continue
+
+                        variable_match = re.match(r'^([A-Z0-9\_]+)\s?\=\s?(.*)$', line)
+                        if not variable_match:
+                            continue
+
+                        # Set the values that we read from the
+                        # file into the cache
+                        key, value = variable_match.groups()
+                        self._cache[key] = value
+
+            # Once the files are loaded, check the system environment
+            # variables. They will override the values from the files
+            # if they exists in the system environment.
+            system_environ = os.environ
+            skip_keys = list(system_environ.keys())
+            # Set the environment variables from the local cache into the system environment
+            # This is necessary for the environment variables to be accessible from
+            # the system environment
+            for key, value in self._cache.items():
+                if key in skip_keys:
+                    continue
+                os.environ.setdefault(key, value)
+
+            # In the specific case of Docker environments for example,
+            # since .env files are not used, load all the environment variables
+            # from the system environment
+            for key, value in system_environ.items():
+                self._cache[key] = value
+
+        os.environ.setdefault('TURBO_ENV_LOADED_FILES', 'True')
+
+    def get(self, name: str) -> TypeAny:
+        """A strict version of the `get` method that raises a KeyError 
+        if the specified environment variable does not exist."""
+        try:
+            return self._cache[name]
+        except KeyError as e:
+            raise exceptions.MissingEnvVariableError(name) from e
+
+    def boolean(self, name: str, default: bool | None = None) -> bool | None:
+        """Returns the value of the specified environment variable as a boolean.
+
+        .. code-block:: python
+
+            turbo_env.boolean("MY_BOOLEAN_ENV_VAR", default=True)
+
+        Args:
+            name (str): The name of the environment variable to retrieve.
+            default (bool | None, optional): The default value to return if the environment variable is not set. Defaults to None.
+
+        Returns:
+            bool | None: The boolean value of the environment variable, or the default if not set.
+        """
+        booleans = ['true', '1', 'yes', 'on', 'false', '0', 'no', 'off']
+
+        value = self._cache.get(name, None)
+        if value is None:
+            return default
+
+        if value.lower() in booleans[:4]:
+            return True
+        elif value.lower() in booleans[4:]:
+            return False
+        else:
+            raise ValueError(
+                f"Value for {name} is not a valid boolean: {value}")
+
+    def string(self, name: str, default: str | None = None) -> str:
+        """Returns the value of the specified environment variable as a string.
+
+        .. code-block:: python
+
+            turbo_env.string("MY_STRING_ENV_VAR", default="default_value")
+
+        Args:
+            name (str): The name of the environment variable to retrieve.
+            default (str | None, optional): The default value to return if the environment variable is not set. Defaults to None.
+
+        Returns:
+            str: The string value of the environment variable, or the default if not set.
+        """
+        value = self._cache.get(name, None)
+        if value is None:
+            return str(default)
+        return str(value)
+
+    def array[T = str](self, name: str, default: Sequence[T] | None = None, cast_values: Callable[[str], T] = str) -> Sequence[T] | None:
+        """Returns a list of values for the given environment variable name. The values are 
+        expected to be comma-separated in the environment variable.
+
+        Args:
+            name (str): The name of the environment variable to retrieve.
+            default (Sequence[T], optional): The default value to return if the environment variable is not set. Defaults to None.
+            cast_values (Callable[[str], TypeCast] | None, optional): A function to cast each value in the list. Defaults to str.
+        """
+        value = self._cache.get(name, None)
+        if value is None:
+            return default
+
+        single_values = [item for item in value.split(',')]
+
+        casted_values: list[T] = []
+        for item in single_values:
+            casted_value = cast_values(item)
+            if isinstance(casted_value, str):
+                casted_value = casted_value.strip()
+            casted_values.append(casted_value)
+        return casted_values
+    
+    def json(self, name: str, default: Sequence[str] | None = None, cast_values: dict[str, TypeCast] | None = None) -> dict[str, TypeAny]:
+        """Returns the value of the specified environment variable parsed as JSON.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+
+            config = env.json('CONFIG')
+            # config will be the parsed JSON value of the CONFIG environment variable
+
+        Args:
+            name (str): The name of the environment variable to retrieve.
+            default (Sequence[str] | None, optional): The default value to return if the environment variable is not set. Defaults to None.
+            cast_values (dict[str, TypeCast] | None, optional): A dictionary specifying cast functions for specific keys in the JSON object. Defaults to None.
+
+        Raises:
+            ValueError: If the specified environment variable is not set or if its value is not a valid JSON string.
+        """
+        values = self.array(name, default=default, cast_values=str)
+        if values is None:
+            raise ValueError(f"Environment variable '{name}' is not set or is empty.")
+
+        dict_values: dict[str, TypeAny] = {}
+        for value in values:
+            if not isinstance(value, str):
+                continue
+
+            key, value = value.split('=', 1)
+
+            _value = value.strip()
+            if cast_values is not None and key in cast_values:
+                try:
+                    _value = cast_values[key](_value)
+                except Exception as e:
+                    raise ValueError(
+                        f"Value for {key} is not valid according to the provided cast function."
+                    ) from e
+
+            dict_values[key.strip().upper()] = _value
+        return json_module.loads(json_module.dumps(dict_values))
+
+    def str_list(self, name: str, default: Sequence[str] | None = None):
+        """Returns a list of strings for the given environment variable name. 
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+
+            allowed_hosts = env.str_list('ALLOWED_HOSTS')
+            # allowed_hosts will be a list of strings, e.g. ["localhost", "example.com"]
+
+        Args:
+            name (str): The name of the environment variable to retrieve.
+            default (Sequence[str] | None, optional): The default value to return if the environment variable is not set. Defaults to None.
+        """
+        return self.array(name, default=default, cast_values=str)
+
+    def int_list(self, name: str, default: Sequence[int] | None = None):
+        """Returns a list of integers for the given environment variable name.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+
+            port_numbers = env.int_list('PORT_NUMBERS')
+            # port_numbers will be a list of integers, e.g. [80, 443, 8080]
+        """
+        return self.array(name, default=default, cast_values=int)
+
+    def domain_list(self, name: str, default: Sequence[str] | None = None) -> Sequence[str]:
+        """Returns a list of domains for the given environment variable name.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+
+            allowed_domains = env.domain_list('ALLOWED_DOMAINS')
+            # allowed_domains will be a list of domains, e.g. ["example.com", "example.org"]
+        """
+        domains = self.array(name, cast_values=str)
+        if domains is None:
+            return []
+        
+        for domain in domains:
+            parsed = urlparse(domain)
+            if parsed.scheme and parsed.path:
+                raise ValueError(f"Value for {name} is not a valid domain: {domain}")
+        return domains
+
+    def url_list(self, name: str, default: Sequence[str] | None = None, secured: bool = False) -> Sequence[str]:
+        """Returns a list of URLs for the given environment variable name.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+
+            api_endpoints = env.url_list('API_ENDPOINTS')
+            # api_endpoints will be a list of URLs, e.g. ["https://api.example.com", "https://api.example.org"]
+        """
+        urls = self.array(name, default=default, cast_values=str)
+        if urls is None:
+            return []
+
+        for url in urls:
+            parsed = urlparse(url)
+            if not parsed.scheme or not parsed.netloc:
+                raise ValueError(f"Value for {name} is not a valid URL: {url}")
+            
+            if secured and parsed.scheme != "https":
+                raise ValueError(f"Value for {name} is not a secure URL: {url}")
+
+        return urls
+
+    def secret(self, name: str):
+        """Returns the value of the specified secret environment variable. 
+        The value is expected to be base64-encoded.
+
+        Example usage::
+
+            from turboenv import TurboEnv
+
+            env = TurboEnv()
+            env.load_envs('.env')
+
+            db_password = env.secret('DB_PASSWORD')
+            # db_password will be the decoded value of the DB_PASSWORD environment variable
+
+        Args:
+            name (str): The name of the secret environment variable to retrieve.
+
+        Raises:
+            ValueError: If the specified secret environment variable is not set or if its value is not a valid base64-encoded string.
+        """
+        value = self._cache.get(name, None)
+        if value is None:
+            raise ValueError(f"Secret {name} is not set")
+
+        try:
+            # Decode the value from base64
+            decoded_value = base64.b64decode(value).decode('utf-8')
+        except Exception as e:
+            raise ValueError(f"Value for {name} is not a valid base64-encoded string: {value}") from e
+        else:
+            return decoded_value
+
+    def path(self, name: str, check: bool = True) -> pathlib.Path | None:
+        """
+        Retrieves the value of the specified environment variable as a file system path.
+
+        Args:
+            name (str): The name of the environment variable to retrieve.
+            check (bool): If True, raises an error if the environment variable is not set.
+
+        Returns:
+            pathlib.Path: The value of the environment variable as a path.
+
+        Raises:
+            ValueError: If the environment variable is not set and check is True.
+        """
+        value = self._cache.get(name, None)
+        if value is not None:
+            for f in self._files:
+                parent = f.parent.absolute()
+                fullpath = parent.joinpath(value).absolute()
+                # Only work with paths that are within 
+                # the current base directory when the
+                # .env file is located
+                # fullpath.relative_to(parent)
+
+                if check and not fullpath.exists():
+                    raise ValueError(f"Path for environment variable {name} does not exist: {fullpath}")
+
+                return fullpath
+
+    def conditional(self, name: str):
+        """
+        Returns a Conditionals instance for the specified environment variable name, 
+        allowing you to apply conditional logic on the value.
+
+        Args:
+            name (str): The name of the environment variable to apply the conditional logic on.
+        """
+        self.get(name)
+        return Conditionals(self, name)

turboenv-0.2.0a1/src/turboenv/namespaces.py

@@ -0,0 +1,25 @@
+import pathlib
+from collections import defaultdict
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class NamespaceModel(BaseModel):
+    name: str | None = Field(default=None)
+    cache: dict[str, str] = Field(default_factory=dict)
+
+
+class NamespaceValues:
+    _cache: defaultdict[str, NamespaceModel] = defaultdict(lambda: NamespaceModel())
+
+    def __init__(self, name: str, values: dict[str, Any]):
+        self.name = name
+
+        ns = self._cache[name]
+        ns.name = name
+        ns.cache.update(values)
+
+        # ".env" file that was used to load the values
+        # for this namespace, if any
+        self.file: Optional[pathlib.Path] = None

turboenv-0.2.0a1/src/turboenv/plugins.py

@@ -0,0 +1,17 @@
+from turboenv.typings import TypeTurboEnv
+
+CACHE_SCHEMES = {
+    'dbcache': 'django.core.cache.backends.db.DatabaseCache',
+    'dummycache': 'django.core.cache.backends.dummy.DummyCache',
+    'filecache': 'django.core.cache.backends.filebased.FileBasedCache',
+    'locmemcache': 'django.core.cache.backends.locmem.LocMemCache',
+    'memcache': 'django.core.cache.backends.memcached.MemcachedCache',
+}
+
+
+def django_plugin(instance: TypeTurboEnv):
+    """A plugin for Django projects that loads environment variables from .env files 
+    and sets them in the system environment.
+    """
+
+

turboenv-0.2.0a1/src/turboenv/typings.py

@@ -0,0 +1,10 @@
+from typing import TYPE_CHECKING, Any, Type
+    
+if TYPE_CHECKING:
+    from turboenv.main import TurboEnv
+
+type TypeAny = str | bool | float | list[str] | dict[str, Any] | None
+
+type TypeCast[T = str | int | float] = Type[T]
+
+type TypeTurboEnv  = 'TurboEnv'