usekit 0.1.2__tar.gz → 0.1.26__tar.gz

{usekit-0.1.2/usekit.egg-info → usekit-0.1.26}/PKG-INFO

@@ -1,18 +1,40 @@
 Metadata-Version: 2.4
 Name: usekit
-Version: 0.1.2
+Version: 0.1.26
 Summary: Minimal input, auto path toolkit (mobile-first, Colab+Drive)
+Home-page: https://github.com/ropnfop/usekit
 Author: ropnfop
 Author-email: withropnfop@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-Requires-Dist: PyYAML>=5.1
-Requires-Dist: python-dotenv>=0.19.0
+Provides-Extra: full
+Requires-Dist: PyYAML>=5.1; extra == "full"
+Requires-Dist: python-dotenv>=0.10.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: PyYAML>=5.1; extra == "dev"
+Requires-Dist: python-dotenv>=0.10.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
 Dynamic: author
 Dynamic: author-email
+Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
-Dynamic: requires-dist
+Dynamic: home-page
+Dynamic: provides-extra
 Dynamic: requires-python
 Dynamic: summary
 
@@ -27,7 +49,7 @@ from usekit import u
 
 u.wjb({"hello": "world"}, "config")     # write json to base
 data = u.rjb("config")                  # read json from base
-u.ujb({"version": "0.1.2"}, "config")   # update json
+u.ujb({"version": "0.1.26"}, "config")   # update json
 ```
 
 **3-letter interface**: Verb + Format + Location  
@@ -62,7 +84,7 @@ data = s.rjb("missing") or {}           # no exceptions
 
 ## Status
 
-- **Version**: 0.1.2 (Alpha)
+- **Version**: 0.1.26 (Alpha)
 - **API**: May change
 - **PyPI**: https://pypi.org/project/usekit
 

{usekit-0.1.2 → usekit-0.1.26}/README.md

@@ -9,7 +9,7 @@ from usekit import u
 
 u.wjb({"hello": "world"}, "config")     # write json to base
 data = u.rjb("config")                  # read json from base
-u.ujb({"version": "0.1.2"}, "config")   # update json
+u.ujb({"version": "0.1.26"}, "config")   # update json
 ```
 
 **3-letter interface**: Verb + Format + Location  
@@ -44,7 +44,7 @@ data = s.rjb("missing") or {}           # no exceptions
 
 ## Status
 
-- **Version**: 0.1.2 (Alpha)
+- **Version**: 0.1.26 (Alpha)
 - **API**: May change
 - **PyPI**: https://pypi.org/project/usekit
 

usekit-0.1.26/setup.py

@@ -0,0 +1,80 @@
+from setuptools import setup, find_packages
+from pathlib import Path
+
+HERE = Path(__file__).parent
+
+def read_readme() -> str:
+    """
+    Read README.md with fallback for TestPyPI upload.
+    Prevents upload failures/warnings when README is missing.
+    """
+    readme = HERE / "README.md"
+    if readme.exists():
+        return readme.read_text(encoding="utf-8")
+    # Fallback description for TestPyPI
+    return "# usekit\n\nMinimal input, auto path toolkit (mobile-first, Colab+Drive)\n"
+
+setup(
+    name="usekit",
+    version="0.1.26",
+    author="ropnfop",
+    author_email="withropnfop@gmail.com",
+    description="Minimal input, auto path toolkit (mobile-first, Colab+Drive)",
+    long_description=read_readme(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/ropnfop/usekit",
+
+    # Key: Exclude unnecessary folders from distribution
+    # (tests, docs, examples not needed in wheel)
+    packages=find_packages(exclude=("tests*", "docs*", "examples*")),
+    include_package_data=True,
+
+    # Key: Only include essential files in wheel
+    # These files MUST be present in the distribution
+    package_data={
+        "usekit": [
+            ".env.example",
+            "sys/sys_yaml/sys_const.yaml",
+        ],
+    },
+
+    python_requires=">=3.8",
+
+    # Zero dependencies: loader_env.py auto-installs when needed
+    # This completely eliminates pip dependency conflicts
+    install_requires=[],
+
+    # Optional dependencies for users who want pre-installation
+    extras_require={
+        "full": [
+            "PyYAML>=5.1",
+            "python-dotenv>=0.10.0",
+        ],
+        "dev": [
+            "PyYAML>=5.1",
+            "python-dotenv>=0.10.0",
+            "pytest>=7.0",
+            "black>=22.0",
+            "flake8>=4.0",
+        ],
+    },
+
+    # Key: Prevent file access issues when installed as zip
+    # Especially important for mobile/Termux environments
+    zip_safe=False,
+
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Operating System :: OS Independent",
+        "Environment :: Console",
+    ],
+)

usekit-0.1.26/usekit/.env.example

@@ -0,0 +1,80 @@
+# USEKIT Environment Configuration
+# ================================================================================
+# This file is automatically used to create .env with smart path binding
+# Copy this to .env and adjust values as needed
+# ================================================================================
+
+# ────────────────────────────────────────────────────────────────────────────
+# [REQUIRED] Base project path - Auto-detected by environment
+# ────────────────────────────────────────────────────────────────────────────
+# USEKIT will automatically set this based on your environment:
+#
+# Termux (Android):  /storage/emulated/0/projects/pj01
+# Google Colab:      /content/drive/MyDrive/PROJECT
+# Local Dev:         Detected from usekit package location
+# Pip Install:       You MUST set this manually
+#
+# Override auto-detection by uncommenting and setting manually:
+# ENV_BASE_PATH=/path/to/your/project
+
+# ────────────────────────────────────────────────────────────────────────────
+# [OPTIONAL] API Keys & Services
+# ────────────────────────────────────────────────────────────────────────────
+# Add your API keys here (these will be masked in logs)
+
+# OpenAI API
+# OPENAI_API_KEY=sk-your-key-here
+
+# Anthropic Claude API
+# ANTHROPIC_API_KEY=sk-ant-your-key-here
+
+# Google APIs
+# GOOGLE_API_KEY=your-key-here
+
+# Other services
+# PINECONE_API_KEY=your-key-here
+# LANGCHAIN_API_KEY=your-key-here
+
+# ────────────────────────────────────────────────────────────────────────────
+# [OPTIONAL] Database Configuration
+# ────────────────────────────────────────────────────────────────────────────
+# DB_HOST=localhost
+# DB_PORT=5432
+# DB_NAME=mydb
+# DB_USER=user
+# DB_PASSWORD=password
+
+# ────────────────────────────────────────────────────────────────────────────
+# [OPTIONAL] Application Settings
+# ────────────────────────────────────────────────────────────────────────────
+# DEBUG=false
+# LOG_LEVEL=INFO
+# TIMEZONE=Asia/Seoul
+
+# ────────────────────────────────────────────────────────────────────────────
+# Platform-Specific Notes
+# ────────────────────────────────────────────────────────────────────────────
+#
+# TERMUX USERS:
+# - Default path: /storage/emulated/0/projects
+# - This directory will be auto-created if it doesn't exist
+# - Make sure Termux has storage permission: run 'termux-setup-storage'
+# - Alternative path: ~/u_project (inside Termux home)
+#
+# GOOGLE COLAB USERS:
+# - Mount Google Drive first: from google.colab import drive; drive.mount('/content/drive')
+# - Default path: /content/drive/MyDrive/PROJECT
+# - Will fallback to /content if Drive not mounted
+#
+# LOCAL DEVELOPMENT:
+# - Path is auto-detected from usekit package location
+# - Typically: /path/to/your/project (where usekit/ folder exists)
+#
+# PIP INSTALLED:
+# - ENV_BASE_PATH is REQUIRED and must be set manually
+# - Choose a location for your project files
+# - Example: ENV_BASE_PATH=/home/user/myproject
+#
+# ────────────────────────────────────────────────────────────────────────────
+# End of configuration
+# ────────────────────────────────────────────────────────────────────────────

usekit-0.1.26/usekit/classes/common/init/helper_termux_storage.py

@@ -0,0 +1,283 @@
+# Path: usekit.classes.common.init.helper_termux_storage.py
+# ----------------------------------------------------------------------------------------------- 
+#  a creation by: THE Little Prince, in harmony with ROP and FOP
+#  — memory is emotion —
+# ----------------------------------------------------------------------------------------------- 
+
+"""
+Termux Storage Permission Helper
+
+Provides user-friendly setup for Termux external storage access.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def is_termux() -> bool:
+    """Check if running in Termux environment"""
+    # Check environment variables
+    if os.environ.get('TERMUX_VERSION'):
+        return True
+    
+    # Check typical Termux paths
+    termux_indicators = [
+        Path('/data/data/com.termux'),
+        Path.home() / '.termux',
+    ]
+    
+    for indicator in termux_indicators:
+        if indicator.exists():
+            return True
+    
+    # Check PREFIX variable
+    prefix = os.environ.get('PREFIX', '')
+    if 'com.termux' in prefix:
+        return True
+    
+    return False
+
+
+def check_storage_permission() -> bool:
+    """
+    Check if external storage is accessible
+    
+    Returns:
+        bool: True if storage is accessible with write permission
+    """
+    try:
+        # Check if path exists and is writable
+        storage_path = Path('/storage/emulated/0')
+        
+        if not storage_path.exists():
+            return False
+        
+        # Try to check write permission
+        return os.access(storage_path, os.W_OK)
+        
+    except Exception:
+        return False
+
+
+def check_storage_status(verbose: bool = False) -> dict:
+    """
+    Get detailed storage permission status
+    
+    Args:
+        verbose: Print status information
+    
+    Returns:
+        dict: Status information
+    """
+    status = {
+        'is_termux': is_termux(),
+        'storage_exists': Path('/storage/emulated/0').exists(),
+        'storage_writable': check_storage_permission(),
+        'ready': False
+    }
+    
+    status['ready'] = status['is_termux'] and status['storage_writable']
+    
+    if verbose:
+        print("\n" + "="*60)
+        print("[USEKIT] Storage Permission Status")
+        print("="*60)
+        print(f"  Termux Environment: {'✓' if status['is_termux'] else '✗'}")
+        print(f"  Storage Exists:     {'✓' if status['storage_exists'] else '✗'}")
+        print(f"  Storage Writable:   {'✓' if status['storage_writable'] else '✗'}")
+        print(f"  Overall Status:     {'READY ✓' if status['ready'] else 'NOT READY ✗'}")
+        print("="*60 + "\n")
+    
+    return status
+
+
+def setup_termux_storage(verbose: bool = True, interactive: bool = True) -> bool:
+    """
+    Setup Termux external storage permissions
+    
+    This will request Android storage permissions and set up access
+    to /storage/emulated/0 for file operations.
+    
+    Args:
+        verbose: Print detailed information
+        interactive: Ask for user confirmation before proceeding
+    
+    Returns:
+        bool: True if setup succeeded
+    
+    Examples:
+        >>> setup_termux_storage()
+        [USEKIT] Running termux-setup-storage...
+        ✓ Permission granted! Please restart Python.
+    """
+    # Check if in Termux
+    if not is_termux():
+        if verbose:
+            print("[USEKIT] Not running in Termux environment")
+        return False
+    
+    # Check if already has permission
+    if check_storage_permission():
+        if verbose:
+            print("[USEKIT] ✓ External storage already accessible")
+        return True
+    
+    # Show explanation if verbose
+    if verbose:
+        print("\n" + "="*60)
+        print("[USEKIT] External Storage Setup Required")
+        print("="*60)
+        print()
+        print("USEKIT needs access to external storage to:")
+        print("  • Save files to /storage/emulated/0")
+        print("  • Access files from other Android apps")
+        print("  • Create and manage project folders")
+        print("  • Share data with file managers")
+        print()
+        print("This will prompt for Android storage permission.")
+        print("Please grant the permission when asked.")
+        print()
+        print("="*60 + "\n")
+    
+    # Ask for confirmation if interactive
+    if interactive:
+        try:
+            response = input("Continue? [Y/n]: ").strip().lower()
+            if response and response not in ['y', 'yes']:
+                print("[USEKIT] Setup cancelled by user")
+                return False
+        except (EOFError, KeyboardInterrupt):
+            print("\n[USEKIT] Setup cancelled")
+            return False
+    
+    # Run termux-setup-storage
+    if verbose:
+        print("[USEKIT] Running termux-setup-storage...")
+        print("[USEKIT] (A permission dialog will appear)")
+    
+    try:
+        result = subprocess.run(
+            ['termux-setup-storage'],
+            capture_output=False,
+            check=True
+        )
+        
+        # Success message
+        if verbose:
+            print()
+            print("="*60)
+            print("[USEKIT] ✓ Permission Granted Successfully!")
+            print("="*60)
+            print()
+            print("Storage access has been configured.")
+            print()
+            print("IMPORTANT: Please restart Python for changes to take effect:")
+            print("  1. Exit Python:    exit()")
+            print("  2. Restart Python: python")
+            print()
+            print("After restarting, you can verify with:")
+            print("  >>> from usekit import use")
+            print("  >>> use.check()")
+            print()
+            print("="*60 + "\n")
+        
+        return True
+        
+    except subprocess.CalledProcessError as e:
+        # Command failed
+        if verbose:
+            print()
+            print("="*60)
+            print("[USEKIT] ✗ Setup Failed")
+            print("="*60)
+            print()
+            print(f"Error: {e}")
+            print()
+            print("Manual setup steps:")
+            print("  1. Exit Python:    exit()")
+            print("  2. Run command:    termux-setup-storage")
+            print("  3. Grant permission when Android prompts you")
+            print("  4. Restart Python: python")
+            print()
+            print("="*60 + "\n")
+        return False
+        
+    except FileNotFoundError:
+        # termux-setup-storage command not found
+        if verbose:
+            print()
+            print("="*60)
+            print("[USEKIT] ✗ Command Not Found")
+            print("="*60)
+            print()
+            print("The 'termux-setup-storage' command was not found.")
+            print()
+            print("Possible causes:")
+            print("  • Not running in Termux")
+            print("  • Termux is outdated (please update)")
+            print()
+            print("Please ensure you are running in Termux and try:")
+            print("  pkg update && pkg upgrade")
+            print()
+            print("="*60 + "\n")
+        return False
+        
+    except KeyboardInterrupt:
+        if verbose:
+            print("\n[USEKIT] Setup cancelled by user")
+        return False
+
+
+def warn_if_not_ready():
+    """
+    Check storage permission and warn user if not ready
+    
+    This is called automatically on import in Termux environments.
+    """
+    if not is_termux():
+        return
+    
+    if check_storage_permission():
+        return
+    
+    # Not ready - show warning
+    print()
+    print("="*60)
+    print("[USEKIT] External Storage: NOT READY")
+    print("="*60)
+    print()
+    print("USEKIT requires external storage permission to work properly.")
+    print()
+    print("Quick fix:")
+    print("  >>> from usekit import use")
+    print("  >>> use.termux()")
+    print()
+    print("Or manually in shell:")
+    print("  $ termux-setup-storage")
+    print()
+    print("="*60 + "\n")
+
+
+# Convenience function for use.py
+def termux(verbose: bool = True, interactive: bool = True) -> bool:
+    """
+    Convenience wrapper for setup_termux_storage
+    
+    Usage:
+        >>> from usekit import use
+        >>> use.termux()
+    """
+    return setup_termux_storage(verbose=verbose, interactive=interactive)
+
+
+def check(verbose: bool = True) -> dict:
+    """
+    Check USEKIT environment status
+    
+    Usage:
+        >>> from usekit import use
+        >>> use.check()
+    """
+    return check_storage_status(verbose=verbose)