dreamstack 0.0.1__tar.gz

dreamstack-0.0.1/LICENSE

@@ -0,0 +1,3 @@
+# Scape Agency Software License Agreement
+
+Copyright 2025 Scape Agency BV, All rights reserved.

dreamstack-0.0.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: dreamstack
+Version: 0.0.1
+Summary: A Python library for demonstration and publishing to PyPI.
+License-File: LICENSE
+Keywords: scape,dreamstack
+Author: Scape Agency
+Author-email: info@scape.agency
+Maintainer: Lars van Vianen
+Maintainer-email: lars@scape.agency
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
+Requires-Dist: rite (>=0.0.13,<0.0.14)
+Project-URL: Documentation, https://github.com/scape-agency/dreamstack/doc
+Project-URL: Homepage, https://scape.agency/
+Project-URL: Repository, https://github.com/scape-agency/dreamstack
+Description-Content-Type: text/markdown
+
+<div align="right">
+
+[![devContainer](https://img.shields.io/badge/devContainer-233696c1?style=flat-square&logo=Docker&logoColor=%23FFFFFF&labelColor=%233696c1&color=%233696c1)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/scape-agency/dreamstack)
+
+</div>
+
+<header>
+<p align="center">
+    <img src="res/logo/dreamstack-logo.png" width="20%" alt="Dreamstack Logo">
+</p>
+<h1 align='center' style='border-bottom: none;'>Dreamstack</h1>
+<h3 align='center'>Scape Agency</h3>
+</header>
+
+<br/>
+
+---
+
+A Python library for demonstration and publishing to PyPI.
+
+---
+
+## Installation
+
+```bash
+pip install dreamstack
+```
+
+---
+
+## Usage
+
+```python
+from dreamstack import hello
+
+print(hello("Scape"))
+```
+
+---
+
+## Project Structure
+
+``` sh
+src/dreamstack/
+├── __init__.py      # Package initialization with namespace support
+├── __version__.py   # Version management
+├── __main__.py      # CLI interface
+└── core.py          # Core greeting functions (hello, greet, format_message)
+```
+
+---
+
+<p align="center">
+    <b>Made with ❤️ by <a href="https://www.scape.agency" target="_blank">Scape Agency</a></b><br/>
+    <sub>Copyright 2026 Scape Agency. All Rights Reserved</sub>
+</p>
+

dreamstack-0.0.1/README.md

@@ -0,0 +1,56 @@
+<div align="right">
+
+[![devContainer](https://img.shields.io/badge/devContainer-233696c1?style=flat-square&logo=Docker&logoColor=%23FFFFFF&labelColor=%233696c1&color=%233696c1)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/scape-agency/dreamstack)
+
+</div>
+
+<header>
+<p align="center">
+    <img src="res/logo/dreamstack-logo.png" width="20%" alt="Dreamstack Logo">
+</p>
+<h1 align='center' style='border-bottom: none;'>Dreamstack</h1>
+<h3 align='center'>Scape Agency</h3>
+</header>
+
+<br/>
+
+---
+
+A Python library for demonstration and publishing to PyPI.
+
+---
+
+## Installation
+
+```bash
+pip install dreamstack
+```
+
+---
+
+## Usage
+
+```python
+from dreamstack import hello
+
+print(hello("Scape"))
+```
+
+---
+
+## Project Structure
+
+``` sh
+src/dreamstack/
+├── __init__.py      # Package initialization with namespace support
+├── __version__.py   # Version management
+├── __main__.py      # CLI interface
+└── core.py          # Core greeting functions (hello, greet, format_message)
+```
+
+---
+
+<p align="center">
+    <b>Made with ❤️ by <a href="https://www.scape.agency" target="_blank">Scape Agency</a></b><br/>
+    <sub>Copyright 2026 Scape Agency. All Rights Reserved</sub>
+</p>

dreamstack-0.0.1/README_PYPI.md

@@ -0,0 +1,191 @@
+# Dreamstack
+
+**A lightweight Python core library for the Dreamstack ecosystem.**
+
+[![PyPI version](https://img.shields.io/pypi/v/dreamstack.svg)](https://pypi.org/project/dreamstack/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dreamstack.svg)](https://pypi.org/project/dreamstack/)
+[![License](https://img.shields.io/pypi/l/dreamstack.svg)](https://pypi.org/project/dreamstack/)
+
+---
+
+## Installation
+
+Install Dreamstack using pip:
+
+```bash
+pip install dreamstack
+```
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from dreamstack import hello
+
+# Simple greeting
+print(hello("World"))
+# Output: Hello, World! Welcome to the dreamstack library.
+
+print(hello("Alice"))
+# Output: Hello, Alice! Welcome to the dreamstack library.
+```
+
+### Custom Greetings
+
+```python
+from dreamstack import greet
+
+# Customizable greeting
+print(greet("Alice"))
+# Output: Hello, Alice!
+
+print(greet("Bob", "Hi"))
+# Output: Hi, Bob!
+
+print(greet("Charlie", greeting="Hey"))
+# Output: Hey, Charlie!
+```
+
+### Message Formatting
+
+```python
+from dreamstack import format_message
+
+# Basic message
+print(format_message("Alice", "Welcome aboard"))
+# Output: Alice: Welcome aboard
+
+# With prefix
+print(format_message("Bob", "Great work", prefix="[INFO]"))
+# Output: [INFO] Bob: Great work
+
+# With suffix
+print(format_message("Charlie", "Task completed", suffix="✓"))
+# Output: Charlie: Task completed ✓
+
+# With both
+print(format_message("Diana", "Login successful", prefix="[SUCCESS]", suffix="🎉"))
+# Output: [SUCCESS] Diana: Login successful 🎉
+```
+
+---
+
+## Command-Line Interface
+
+Dreamstack also provides a simple CLI:
+
+```bash
+# Basic greeting
+python -m dreamstack Alice
+# Output: Hello, Alice! Welcome to the dreamstack library.
+
+# Show version
+python -m dreamstack --version
+
+# Verbose output
+python -m dreamstack Bob --verbose
+# Output:
+# Hello, Bob! Welcome to the dreamstack library.
+# [Dreamstack v0.1.2]
+
+# Help
+python -m dreamstack --help
+```
+
+---
+
+## Features
+
+- **Simple API**: Easy-to-use functions for common greeting tasks
+- **Type-safe**: Full type hints for better IDE support
+- **Validated**: Input validation with helpful error messages
+- **CLI Support**: Use as a command-line tool
+- **Namespace Package**: Designed to support ecosystem extensions
+- **Well-documented**: Comprehensive docstrings and examples
+
+---
+
+## API Reference
+
+### `hello(name: str) -> str`
+
+Returns a welcoming greeting message.
+
+**Parameters:**
+- `name` (str): The name to greet (non-empty string)
+
+**Returns:**
+- str: A formatted greeting message
+
+**Raises:**
+- `TypeError`: If name is not a string
+- `ValueError`: If name is empty or whitespace-only
+
+---
+
+### `greet(name: str, greeting: str = "Hello") -> str`
+
+Returns a customizable greeting message.
+
+**Parameters:**
+- `name` (str): The name to greet (non-empty string)
+- `greeting` (str): The greeting word (default: "Hello")
+
+**Returns:**
+- str: A formatted greeting with custom greeting
+
+**Raises:**
+- `TypeError`: If name or greeting is not a string
+- `ValueError`: If name or greeting is empty or whitespace-only
+
+---
+
+### `format_message(name: str, message: str, prefix: str | None = None, suffix: str | None = None) -> str`
+
+Formats a message with optional prefix and suffix.
+
+**Parameters:**
+- `name` (str): The name to include in the message
+- `message` (str): The main message content
+- `prefix` (str | None): Optional prefix before the message
+- `suffix` (str | None): Optional suffix after the message
+
+**Returns:**
+- str: A formatted message string
+
+**Raises:**
+- `TypeError`: If arguments are not strings (where required)
+- `ValueError`: If name or message is empty or whitespace-only
+
+---
+
+## Requirements
+
+- Python >= 3.12, < 3.13
+
+---
+
+## License
+
+Proprietary License. Copyright © 2025 [Scape Agency](https://www.scape.agency).
+
+---
+
+## Links
+
+- **Homepage**: [https://www.scape.agency](https://www.scape.agency)
+- **PyPI**: [https://pypi.org/project/dreamstack/](https://pypi.org/project/dreamstack/)
+- **Issues**: Report bugs and request features on our issue tracker
+
+---
+
+## Support
+
+For questions and support, please contact [info@scape.agency](mailto:info@scape.agency).
+
+---
+
+**Made with 💙 by Scape Agency**

dreamstack-0.0.1/pyproject.toml

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+
+
+# =============================================================================
+# Project Configuration
+# =============================================================================
+
+[project]
+name = "dreamstack"
+version = "0.0.1"
+description = "A Python library for demonstration and publishing to PyPI."
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+authors = [{ name = "Scape Agency", email = "info@scape.agency" }]
+maintainers = [{ name = "Lars van Vianen", email = "lars@scape.agency" }]
+keywords = ["scape", "dreamstack"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Internet :: WWW/HTTP :: WSGI",
+]
+
+
+# =============================================================================
+# Project URLs
+# =============================================================================
+
+[project.urls]
+homepage = "https://scape.agency/"
+repository = "https://github.com/scape-agency/dreamstack"
+documentation = "https://github.com/scape-agency/dreamstack/doc"
+
+# =============================================================================
+# Poetry
+# =============================================================================
+
+[tool.poetry]
+package-mode = true
+packages = [{ include = "dreamstack", from = "src" }]
+include = [
+    "src/**",
+    # "README.md",
+    "README_PYPI.md",
+    "LICENSE",
+    # "docs/**",   # Include documentation in the package
+]
+
+# =============================================================================
+# Dependencies
+# =============================================================================
+
+[tool.poetry.dependencies]
+python = ">=3.12, <4.0"
+rite = "^0.0.13"
+
+
+# =============================================================================
+# Development Dependencies
+# =============================================================================
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.3.5"     # Framework for testing
+pytest-cov = ">=6.1.1" # Code coverage for tests
+black = "^25.1.0"      # Code formatter
+flake8 = "^7.2.0"      # Linter for code quality
+mypy = "^1.19.1"       # Static type checker
+sphinx = ">=8.0.2"     # Documentation generator
+isort = ">=6,<8"       # Import sorter
+tox = "^4.25.0"        # Testing multiple environments
+pre-commit = "^4.5.1"  # Pre-commit hooks for linting and formatting
+
+
+# =============================================================================
+# Build System
+# =============================================================================
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+# =============================================================================
+# Scripts
+# =============================================================================
+
+[tool.poetry.scripts]
+dreamstack_base = "dreamstack_base.__main__:main"
+test = "bin.run_tests:main"

dreamstack-0.0.1/src/dreamstack/__init__.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+
+
+# =============================================================================
+# Docstring
+# =============================================================================
+
+"""
+Dreamstack - A Python Library
+=============================
+
+Dreamstack is a demonstration library for publishing to PyPI, showcasing best practices
+in Python package development.
+
+This package provides utilities for greeting and message formatting, with comprehensive
+error handling and type safety.
+
+Examples:
+    Basic usage::
+
+        >>> from dreamstack import hello
+        >>> hello("Scape")
+        'Hello, Scape! Welcome to the dreamstack library.'
+
+    Advanced usage::
+
+        >>> from dreamstack import greet, format_message
+        >>> greet("Alice", "Hi")
+        'Hi, Alice!'
+        >>> format_message("Bob", "Task done", prefix="[INFO]")
+        '[INFO] Bob: Task done'
+
+Attributes:
+    __version__: The version string for this package.
+    __version_info__: A tuple of version components.
+
+"""
+
+# =============================================================================
+# Imports
+# =============================================================================
+
+# Import | Standard Library
+from typing import Iterable
+
+# Import | Local
+from dreamstack.__version__ import __version__, __version_info__
+from dreamstack.core import format_message, greet, hello
+
+# =============================================================================
+# Package Initialization
+# =============================================================================
+
+# Enable namespace package support
+__path__: Iterable[str]
+__path__ = __import__(name="pkgutil").extend_path(
+    __path__,
+    __name__,
+)
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+# Public API exports
+__all__: list[str] = [
+    # Version information
+    "__version__",
+    "__version_info__",
+    # Core functions
+    "hello",
+    "greet",
+    "format_message",
+]

dreamstack-0.0.1/src/dreamstack/__main__.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+
+
+# =============================================================================
+# Docstring
+# =============================================================================
+
+"""
+Dreamstack - Command-Line Interface
+===================================
+
+Command-line interface for Dreamstack library.
+
+Provides a simple CLI to greet users using the dreamstack library.
+
+Examples:
+    Basic usage::
+
+        $ python -m dreamstack --version
+        dreamstack 0.0.1
+
+        $ python -m dreamstack Alice
+        Hello, Alice! Welcome to the dreamstack library.
+
+    With verbose output::
+
+        $ python -m dreamstack Bob --verbose
+        Hello, Bob! Welcome to the dreamstack library.
+
+        [Dreamstack v0.0.1]
+
+"""
+
+# =============================================================================
+# Imports
+# =============================================================================
+
+# Import | Standard Library
+import argparse
+import sys
+from typing import Optional, Sequence
+
+# Import | Local
+from dreamstack import __version__, hello
+
+# =============================================================================
+# Functions
+# =============================================================================
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="dreamstack",
+        description="Dreamstack - A Python library for demonstration and publishing to PyPI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Show program version and exit",
+    )
+
+    parser.add_argument(
+        "name",
+        nargs="?",
+        default="World",
+        help="Name to greet (default: World)",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose output",
+    )
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """
+    Main entry point for the CLI.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv)
+
+    Returns:
+        Exit code (0 for success, non-zero for failure)
+
+    """
+
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        greeting = hello(args.name)
+        print(greeting)
+
+        if args.verbose:
+            print(f"\n[Dreamstack v{__version__}]")
+
+        return 0
+
+    except (ValueError, TypeError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    except KeyboardInterrupt:
+        print("\nInterrupted", file=sys.stderr)
+        return 130
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+if __name__ == "__main__":
+    sys.exit(main())

dreamstack-0.0.1/src/dreamstack/__version__.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+
+
+# =============================================================================
+# Docstring
+# =============================================================================
+
+"""
+Dreamstack - Version Information
+================================
+
+Version information for Dreamstack package.
+
+"""
+
+
+# =============================================================================
+# Version Information
+# =============================================================================
+
+__version__ = "0.0.1"
+__version_info__ = tuple(int(i) for i in __version__.split(".") if i.isdigit())
+
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+__all__: list[str] = [
+    "__version__",
+    "__version_info__",
+]

dreamstack-0.0.1/src/dreamstack/core.py

@@ -0,0 +1,203 @@
+# -*- coding: utf-8 -*-
+
+
+# =============================================================================
+# Docstring
+# =============================================================================
+
+"""
+Dreamstack - Core Module
+========================
+
+This module contains the core functionality of the Dreamstack library.
+
+Examples:
+    Basic greeting::
+
+        >>> from dreamstack.core import hello
+        >>> hello("Scape")
+        'Hello, Scape! Welcome to the dreamstack library.'
+
+    Customized greeting::
+
+        >>> greet("Scape", greeting="Hi")
+        'Hi, Scape!'
+
+"""
+
+# =============================================================================
+# Imports
+# =============================================================================
+
+from typing import Optional
+
+# =============================================================================
+# Functions
+# =============================================================================
+
+
+def hello(name: str) -> str:
+    """
+    Return a simple greeting message.
+
+    This function provides a welcoming greeting message for the dreamstack
+    library.
+
+    Args:
+        name: The name of the person or entity to greet. Must be a non-empty
+            string.
+
+    Returns:
+        A formatted greeting string.
+
+    Raises:
+        ValueError: If name is empty or contains only whitespace.
+        TypeError: If name is not a string.
+
+    Examples:
+        >>> hello("World")
+        'Hello, World! Welcome to the dreamstack library.'
+
+        >>> hello("Alice")
+        'Hello, Alice! Welcome to the dreamstack library.'
+
+    """
+    if not isinstance(name, str):
+        raise TypeError(
+            f"Expected string for 'name', got {type(name).__name__}"
+        )
+
+    if not name.strip():
+        raise ValueError("Name cannot be empty or contain only whitespace")
+
+    return f"Hello, {name}! Welcome to the dreamstack library."
+
+
+def greet(name: str, greeting: str = "Hello") -> str:
+    """
+    Return a customizable greeting message.
+
+    This function provides a flexible greeting with customizable greeting text.
+
+    Args:
+        name: The name of the person or entity to greet. Must be a non-empty string.
+        greeting: The greeting word to use (default: "Hello").
+
+    Returns:
+        A formatted greeting string with the custom greeting.
+
+    Raises:
+        ValueError: If name or greeting is empty or contains only whitespace.
+        TypeError: If name or greeting is not a string.
+
+    Examples:
+        >>> greet("Alice")
+        'Hello, Alice!'
+
+        >>> greet("Bob", "Hi")
+        'Hi, Bob!'
+
+        >>> greet("Charlie", greeting="Hey")
+        'Hey, Charlie!'
+
+    """
+    if not isinstance(name, str):
+        raise TypeError(
+            f"Expected string for 'name', got {type(name).__name__}"
+        )
+
+    if not isinstance(greeting, str):
+        raise TypeError(
+            f"Expected string for 'greeting', got {type(greeting).__name__}"
+        )
+
+    if not name.strip():
+        raise ValueError("Name cannot be empty or contain only whitespace")
+
+    if not greeting.strip():
+        raise ValueError("Greeting cannot be empty or contain only whitespace")
+
+    return f"{greeting}, {name}!"
+
+
+def format_message(
+    name: str,
+    message: str,
+    prefix: Optional[str] = None,
+    suffix: Optional[str] = None,
+) -> str:
+    """
+    Format a message with optional prefix and suffix.
+
+    This function provides advanced message formatting capabilities.
+
+    Args:
+        name: The name to include in the message.
+        message: The main message content.
+        prefix: Optional prefix to add before the message.
+        suffix: Optional suffix to add after the message.
+
+    Returns:
+        A formatted message string.
+
+    Raises:
+        ValueError: If name or message is empty.
+        TypeError: If arguments are not strings (where required).
+
+    Examples:
+        >>> format_message("Alice", "Welcome aboard")
+        'Alice: Welcome aboard'
+
+        >>> format_message("Bob", "Great work", prefix="[INFO]")
+        '[INFO] Bob: Great work'
+
+        >>> format_message("Charlie", "Task completed", suffix="✓")
+        'Charlie: Task completed ✓'
+
+    """
+    if not isinstance(name, str):
+        raise TypeError(
+            f"Expected string for 'name', got {type(name).__name__}"
+        )
+
+    if not isinstance(message, str):
+        raise TypeError(
+            f"Expected string for 'message', got {type(message).__name__}"
+        )
+
+    if prefix is not None and not isinstance(prefix, str):
+        raise TypeError(
+            f"Expected string for 'prefix', got {type(prefix).__name__}"
+        )
+
+    if suffix is not None and not isinstance(suffix, str):
+        raise TypeError(
+            f"Expected string for 'suffix', got {type(suffix).__name__}"
+        )
+
+    if not name.strip():
+        raise ValueError("Name cannot be empty or contain only whitespace")
+
+    if not message.strip():
+        raise ValueError("Message cannot be empty or contain only whitespace")
+
+    result = f"{name}: {message}"
+
+    if prefix:
+        result = f"{prefix} {result}"
+
+    if suffix:
+        result = f"{result} {suffix}"
+
+    return result
+
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+__all__: list[str] = [
+    "hello",
+    "greet",
+    "format_message",
+]