djangx 1.5.5__py3-none-any.whl → 1.5.7__py3-none-any.whl

djangx/__init__.py

@@ -43,6 +43,10 @@ PROJECT_INIT_NAME: str = PROJECT_DIR.name
 
 PROJECT_MAIN_APP_NAME: str = "home"
 
+# bools
+
+INCLUDE_PROJECT_MAIN_APP: bool = PROJECT_MAIN_APP_DIR.exists() and PROJECT_MAIN_APP_DIR.is_dir()
+
 # Settings configuration classes
 
 _ValueType: TypeAlias = Optional[str | bool | list[str] | pathlib.Path | int]
@@ -206,14 +210,18 @@ class Conf:
 
         except (FileNotFoundError, KeyError, ValueError) as e:
             cls._validated = False
+            print(f"Not in a valid {PKG_DISPLAY_NAME} project directory.", Text.ERROR)
             print(
-                f"Are you currently executing in a {PKG_DISPLAY_NAME} project base directory?\n"
-                f"If not, navigate to your project's root or create a new {PKG_DISPLAY_NAME} project to run the command.\n\n"
-                "A valid project requires:\n"
-                f"  - `pyproject.toml` file with a 'tool.{PKG_NAME}' section (even if empty)\n"
-                f"Validation failed: {e}",
-                Text.WARNING,
+                f"A valid project requires: pyproject.toml with a 'tool.{PKG_NAME}' section (even if empty)",
+                Text.INFO,
+            )
+            print(
+                [
+                    ("Create a new project: ", None),
+                    (f"uvx {PKG_NAME} startproject (if uv is installed.)", Text.HIGHLIGHT),
+                ]
             )
+            print(f"Validation error: {e}")
 
         except Exception as e:
             cls._validated = False

djangx/api/enums.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+
+class DatabaseBackend(StrEnum):
+    """Available database backends."""
+
+    SQLITE3 = "sqlite3"
+    POSTGRESQL = "postgresql"

djangx/api/settings/databases.py

@@ -5,6 +5,7 @@
 # https://www.postgresql.org/docs/current/libpq-pgpass.html
 # ==============================================================================
 from ... import PROJECT_DIR, Conf, ConfField
+from ..enums import DatabaseBackend
 from ..types import DatabaseDict, DatabaseOptionsDict, DatabasesDict
 
 
@@ -13,10 +14,10 @@ class DatabaseConf(Conf):
 
     backend = ConfField(
         type=str,
-        choices=["sqlite3", "postgresql"],
+        choices=[DatabaseBackend.SQLITE3, DatabaseBackend.POSTGRESQL],
         env="DB_BACKEND",
         toml="db.backend",
-        default="sqlite3",
+        default=DatabaseBackend.SQLITE3,
     )
     # postgresql specific
     use_vars = ConfField(
@@ -79,14 +80,14 @@ def _get_databases_config() -> DatabasesDict:
     backend: str = _DATABASE.backend.lower()
 
     match backend:
-        case "sqlite" | "sqlite3":
+        case DatabaseBackend.SQLITE3:
             return {
                 "default": {
-                    "ENGINE": "django.db.backends.sqlite3",
-                    "NAME": PROJECT_DIR / "db.sqlite3",
+                    "ENGINE": f"django.db.backends.{DatabaseBackend.SQLITE3.value}",
+                    "NAME": PROJECT_DIR / f"db.{DatabaseBackend.SQLITE3.value}",
                 }
             }
-        case "postgresql" | "postgres" | "psql" | "pgsql" | "pg" | "psycopg":
+        case DatabaseBackend.POSTGRESQL:
             options: DatabaseOptionsDict = {
                 "pool": _DATABASE.pool,
                 "sslmode": _DATABASE.ssl_mode,
@@ -95,7 +96,7 @@ def _get_databases_config() -> DatabasesDict:
             # Add service or connection vars
             if _DATABASE.use_vars:
                 config: DatabaseDict = {
-                    "ENGINE": "django.db.backends.postgresql",
+                    "ENGINE": f"django.db.backends.{DatabaseBackend.POSTGRESQL.value}",
                     "NAME": _DATABASE.name,
                     "USER": _DATABASE.user,
                     "PASSWORD": _DATABASE.password,
@@ -106,7 +107,7 @@ def _get_databases_config() -> DatabasesDict:
             else:
                 options["service"] = _DATABASE.service
                 config: DatabaseDict = {
-                    "ENGINE": "django.db.backends.postgresql",
+                    "ENGINE": f"django.db.backends.{DatabaseBackend.POSTGRESQL.value}",
                     "NAME": _DATABASE.name,
                     "OPTIONS": options,
                 }

djangx/enums.py

@@ -0,0 +1,2 @@
+from .api.enums import *  # noqa: F403
+from .management.enums import *  # noqa: F403

djangx/management/cli.py

@@ -17,6 +17,7 @@ def main() -> Optional[NoReturn]:
         case "startproject" | "init" | "new":
             from argparse import ArgumentParser, Namespace
 
+            from ..enums import DatabaseBackend
             from .commands.startproject import initialize
 
             parser = ArgumentParser(description=f"Initialize a new {PKG_DISPLAY_NAME} project")
@@ -25,9 +26,21 @@ def main() -> Optional[NoReturn]:
                 choices=["default", "vercel"],
                 help="Project preset to use (skips interactive prompt)",
             )
+            parser.add_argument(
+                "--database",
+                "--db",
+                choices=[DatabaseBackend.SQLITE3, DatabaseBackend.POSTGRESQL],
+                help=f"Database backend to use (skips interactive prompt). Note: Vercel preset requires {DatabaseBackend.POSTGRESQL.value}.",
+            )
+            parser.add_argument(
+                "--force",
+                "-f",
+                action="store_true",
+                help="Skip directory validation and initialize even if directory is not empty",
+            )
             args: Namespace = parser.parse_args(sys.argv[2:])
 
-            sys.exit(initialize(preset=args.preset))
+            sys.exit(initialize(preset=args.preset, database=args.database, force=args.force))
 
         case _:
             from os import environ

djangx/management/commands/generate.py

@@ -1,25 +1,224 @@
-from enum import StrEnum
-from typing import Any
+import builtins
+import pathlib
+from typing import Any, Optional, cast
 
 from christianwhocodes.generators import (
     FileGenerator,
-    FileGeneratorOption,
     PgPassFileGenerator,
     PgServiceFileGenerator,
     SSHConfigFileGenerator,
 )
 from django.core.management.base import BaseCommand, CommandParser
 
-from .generators import EnvFileGenerator, ServerFileGenerator, VercelFileGenerator
+from ... import PKG_DISPLAY_NAME, PKG_NAME, PROJECT_API_DIR, PROJECT_DIR, Conf
+from ..enums import FileOption
 
 
-class FileOption(StrEnum):
-    PG_SERVICE = FileGeneratorOption.PG_SERVICE.value
-    PGPASS = FileGeneratorOption.PGPASS.value
-    SSH_CONFIG = FileGeneratorOption.SSH_CONFIG.value
-    ENV = "env"
-    SERVER = "server"
-    VERCEL = "vercel"
+class _ServerFileGenerator(FileGenerator):
+    f"""
+    Generator for ASGI / WSGI configuration in api/server.py file.
+    
+    Creates an server.py file in the /api directory.
+    Required for running {PKG_DISPLAY_NAME} apps with ASGI or WSGI servers.
+    Note that the type of api gateway dependes on the SERVER_USE_ASGI setting.
+    """
+
+    @property
+    def file_path(self) -> pathlib.Path:
+        """Return the path for the api/server.py"""
+        return PROJECT_API_DIR / "server.py"
+
+    @property
+    def data(self) -> str:
+        """Return template content for api/server.py."""
+        return f"from {PKG_NAME}.api.backends.server import application\n\napp = application\n"
+
+
+class _VercelFileGenerator(FileGenerator):
+    """
+    Generator for Vercel configuration file (vercel.json).
+
+    Creates a vercel.json file in the base directory.
+    Useful for deploying to Vercel with custom install/build commands.
+    """
+
+    @property
+    def file_path(self) -> pathlib.Path:
+        return PROJECT_DIR / "vercel.json"
+
+    @property
+    def data(self) -> str:
+        """Return template content for vercel.json."""
+        lines = [
+            "{",
+            '  "$schema": "https://openapi.vercel.sh/vercel.json",',
+            f'  "installCommand": "uv run {PKG_NAME} runinstall",',
+            f'  "buildCommand": "uv run {PKG_NAME} runbuild",',
+            '  "rewrites": [',
+            "    {",
+            '      "source": "/(.*)",',
+            '      "destination": "/api/server"',
+            "    }",
+            "  ]",
+            "}",
+        ]
+
+        return "\n".join(lines) + "\n"
+
+
+class _EnvFileGenerator(FileGenerator):
+    """
+    Generator for environment configuration file (.env.example).
+
+    Creates a .env.example file in the base directory with all
+    possible environment variables from configuration classes.
+    All variables are commented out by default.
+    """
+
+    @property
+    def file_path(self) -> pathlib.Path:
+        """Return the path for the .env.example file."""
+        return PROJECT_DIR / ".env.example"
+
+    @property
+    def data(self) -> str:
+        """Generate .env file content based on all ConfFields from Conf subclasses."""
+
+        lines: list[str] = []
+
+        # Add header
+        lines.extend(self._add_header())
+
+        # Get all fields from Conf subclasses
+        env_fields = Conf.get_env_fields()
+
+        # Group fields by class
+        fields_by_class: dict[str, list[dict[str, Any]]] = {}
+        for field in env_fields:
+            class_name = cast(str, field["class"])
+            if class_name not in fields_by_class:
+                fields_by_class[class_name] = []
+            fields_by_class[class_name].append(field)
+
+        # Generate content for each class group
+        for class_name in sorted(fields_by_class.keys()):
+            fields = fields_by_class[class_name]
+
+            # Add section header
+            lines.extend(self._add_section_header(class_name))
+
+            # Process each field in this class
+            for field in fields:
+                env_var = field["env"]
+                toml_key = field["toml"]
+                choices_key = field["choices"]
+                default_value = field["default"]
+                field_type = field["type"]
+
+                # Add field documentation with proper format hints
+                lines.append(
+                    f"# Variable: {self._format_variable_hint(env_var, choices_key, field_type)}"
+                )
+                if toml_key:
+                    lines.append(f"# TOML Key: {toml_key}")
+
+                # Format default value for display
+                if default_value is not None:
+                    formatted_default = self._format_default_value(default_value, field_type)
+                    lines.append(f"# Default: {formatted_default}")
+                else:
+                    lines.append("# Default: (none)")
+
+                lines.append(f"# {env_var}=")
+
+                lines.append("")
+
+            lines.append("")
+
+        # Add footer
+        lines.extend(self._add_footer())
+
+        return "\n".join(lines)
+
+    def _add_header(self) -> list[str]:
+        """Add header to the .env.example file."""
+        lines: list[str] = []
+        lines.append("# " + "=" * 78)
+        lines.append(f"# {PKG_DISPLAY_NAME} Environment Configuration")
+        lines.append("# " + "=" * 78)
+        lines.append("#")
+        lines.append("# This file contains all available environment variables for configuration.")
+        lines.append("#")
+        lines.append("# Configuration Priority: ENV > TOML > Default")
+        lines.append("# " + "=" * 78)
+        lines.append("")
+        return lines
+
+    def _add_section_header(self, class_name: str) -> list[str]:
+        """Add section header for a configuration class."""
+        lines: list[str] = []
+        lines.append("# " + "-" * 78)
+        lines.append(f"# {class_name} Configuration")
+        lines.append("# " + "-" * 78)
+        lines.append("")
+        return lines
+
+    def _add_footer(self) -> list[str]:
+        """Add footer to the .env.example file."""
+        lines: list[str] = []
+        lines.append("# " + "=" * 78)
+        lines.append("# End of Configuration")
+        lines.append("# " + "=" * 78)
+        return lines
+
+    def _format_choices(self, choices: list[str]) -> str:
+        """Format choices as 'choice1' | 'choice2' | 'choice3'."""
+        return " | ".join(f'"{choice}"' for choice in choices)
+
+    def _get_type_example(self, field_type: type) -> str:
+        """Get example value for a field type."""
+        match field_type:
+            case builtins.bool:
+                return '"true" | "false"'
+            case builtins.int:
+                return '"123"'
+            case builtins.float:
+                return '"123.45"'
+            case builtins.list:
+                return '"value1,value2,value3"'
+            case pathlib.Path:
+                return '"/full/path/to/something"'
+            case _:
+                return '"value"'
+
+    def _format_variable_hint(
+        self, env_var: str, choices_key: Optional[list[str]], field_type: type
+    ) -> str:
+        """Format variable hint showing proper syntax based on type."""
+        if choices_key:
+            return f"{env_var}={self._format_choices(choices_key)}"
+        else:
+            return f"{env_var}={self._get_type_example(field_type)}"
+
+    def _format_default_value(self, value: Any, field_type: type) -> str:
+        """Format default value for display in comments."""
+        if value is None:
+            return "(none)"
+
+        match field_type:
+            case builtins.bool:
+                return "true" if value else "false"
+            case builtins.list:
+                if isinstance(value, list):
+                    list_items = cast(list[Any], value)
+                    if not list_items:
+                        return "(empty list)"
+                    return ",".join(str(v) for v in list_items)
+                return str(value)
+            case pathlib.Path:
+                return str(pathlib.PurePosixPath(value))
+            case _:
+                return str(value)
 
 
 class Command(BaseCommand):
@@ -48,12 +247,12 @@ class Command(BaseCommand):
         force: bool = options["force"]
 
         generators: dict[FileOption, type[FileGenerator]] = {
-            FileOption.VERCEL: VercelFileGenerator,
-            FileOption.SERVER: ServerFileGenerator,
+            FileOption.VERCEL: _VercelFileGenerator,
+            FileOption.SERVER: _ServerFileGenerator,
             FileOption.PG_SERVICE: PgServiceFileGenerator,
             FileOption.PGPASS: PgPassFileGenerator,
             FileOption.SSH_CONFIG: SSHConfigFileGenerator,
-            FileOption.ENV: EnvFileGenerator,
+            FileOption.ENV: _EnvFileGenerator,
         }
 
         generator_class: type[FileGenerator] = generators[file_option]