Yuvacodes 0.1.0__tar.gz

yuvacodes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyCodes Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yuvacodes-0.1.0/PKG-INFO

@@ -0,0 +1,443 @@
+Metadata-Version: 2.4
+Name: Yuvacodes
+Version: 0.1.0
+Summary: A personal cloud-based code library for Python and Jupyter Notebooks
+Author: MyCodes Contributors
+License-Expression: MIT
+Keywords: code-library,jupyter,snippets,cloud-storage,github,ipython
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: jupyter
+Requires-Dist: ipython>=7.0.0; extra == "jupyter"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# MyCodes 🚀
+
+> **Your personal cloud-based Python code library.** Store code snippets online on GitHub, assign numeric IDs, and retrieve or inject them seamlessly into any computer or Jupyter Notebook over HTTPS with `pip install mycodes`.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Jupyter Supported](https://img.shields.io/badge/Jupyter-IPython%20Magics-orange.svg)](https://jupyter.org/)
+
+---
+
+## 1. What is MyCodes?
+
+When working across multiple computers, remote servers, Google Colab, or Jupyter notebooks, sharing reusable algorithms, helper routines, and starter templates is often clumsy.
+
+**MyCodes** decouples your code library from local storage:
+- **Zero local storage needed**: You don't have to keep a clone of your code library on every machine.
+- **GitHub as Cloud Storage**: Store clean Python files (e.g. `101.py`, `102.py`) in a public GitHub repository with an `index.json` catalog.
+- **Instant Retrieval**: Download source code strings or inject them directly into Jupyter cells using intuitive IDs (`get_code(101)` or `%load_code 101`).
+- **No Hard-coded Usernames**: Easily configure your personal repository via Python, environment variables, or CLI.
+
+---
+
+## 2. Architecture
+
+```text
+                    ┌──────────────────────────────┐
+                    │            GitHub            │
+                    │      Cloud Code Storage      │
+                    │                              │
+                    │  codes/                      │
+                    │    ├── 001.py                │
+                    │    ├── 002.py                │
+                    │    ├── 101.py                │
+                    │    └── ...                   │
+                    │  index.json                  │
+                    └──────────────┬───────────────┘
+                                   │
+                                   │ HTTPS (raw.githubusercontent.com)
+                                   ▼
+                    ┌──────────────────────────────┐
+                    │           MyCodes            │
+                    │        Python Package        │
+                    │         (from PyPI)          │
+                    └──────────────┬───────────────┘
+                                   │
+                             pip install
+                                   │
+                ┌──────────────────┼──────────────────┐
+                ▼                  ▼                  ▼
+          Workstation A      Cloud Notebook      Workstation B
+                │                  │                  │
+             Jupyter             Jupyter            Terminal
+```
+
+---
+
+## 3. GitHub Repository Setup
+
+To host your code library in the cloud:
+
+1. Create a public repository on GitHub (e.g., `my-code-library`).
+2. Add a `codes/` folder and an `index.json` file in the root:
+
+```text
+my-code-library/
+├── codes/
+│   ├── 001.py
+│   ├── 002.py
+│   ├── 101.py
+│   └── 102.py
+└── index.json
+```
+
+### Example `codes/101.py`
+```python
+def hello():
+    print("Hello from Code 101")
+```
+
+### Example `index.json`
+```json
+{
+  "001": {
+    "name": "Hello World",
+    "description": "Simple Hello World example",
+    "category": "Basics",
+    "language": "python",
+    "tags": ["hello", "basics", "starter"],
+    "file": "codes/001.py"
+  },
+  "002": {
+    "name": "Addition",
+    "description": "Simple addition function",
+    "category": "Math",
+    "language": "python",
+    "tags": ["math", "add", "arithmetic"],
+    "file": "codes/002.py"
+  },
+  "101": {
+    "name": "Greeting 101",
+    "description": "Greeting function for code 101",
+    "category": "Basics",
+    "language": "python",
+    "tags": ["hello", "101"],
+    "file": "codes/101.py"
+  }
+}
+```
+
+Push these files to the `main` branch of your GitHub repository.
+
+---
+
+## 4. Installation
+
+Install the core package:
+
+```bash
+pip install mycodes
+```
+
+Or install with optional Jupyter/IPython support:
+
+```bash
+pip install mycodes[jupyter]
+```
+
+---
+
+## 5. Configuration
+
+Do not hard-code repository details. You can configure your repository in three convenient ways:
+
+### Option A: Python API
+```python
+from mycodes import configure
+
+configure(
+    username="YOUR_GITHUB_USERNAME",
+    repository="my-code-library", # Defaults to 'my-code-library'
+    branch="main",                 # Defaults to 'main'
+    persist=True                   # Optionally save to ~/.mycodes/config.json
+)
+```
+
+### Option B: Environment Variables
+Add these to your shell profile (`.bashrc`, `.zshrc`, or Windows Environment Variables):
+
+```bash
+export MYCODES_GITHUB_USER="YOUR_GITHUB_USERNAME"
+export MYCODES_GITHUB_REPO="my-code-library"
+export MYCODES_GITHUB_BRANCH="main"
+```
+
+### Option C: Command Line Interface
+```bash
+mycodes config --username YOUR_GITHUB_USERNAME --repository my-code-library
+```
+
+---
+
+## 6. Adding a New Code
+
+Adding a new snippet to your cloud library takes three simple steps:
+
+1. **Write your Python code** and save it as `codes/103.py`:
+   ```python
+   def binary_search(arr, target):
+       low, high = 0, len(arr) - 1
+       while low <= high:
+           mid = (low + high) // 2
+           if arr[mid] == target:
+               return mid
+           elif arr[mid] < target:
+               low = mid + 1
+           else:
+               high = mid - 1
+       return -1
+   ```
+
+2. **Register it in `index.json`**:
+   ```json
+   "103": {
+     "name": "Binary Search",
+     "description": "Binary search algorithm on sorted list",
+     "category": "DSA",
+     "language": "python",
+     "tags": ["search", "binary search", "dsa"],
+     "file": "codes/103.py"
+   }
+   ```
+
+3. **Commit & Push to GitHub**:
+   ```bash
+   git add codes/103.py index.json
+   git commit -m "Add code 103: Binary Search"
+   git push origin main
+   ```
+
+It is instantly live and accessible from anywhere in the world!
+
+---
+
+## 7. Getting a Code
+
+Retrieve code directly over HTTPS:
+
+```python
+from mycodes import get_code
+
+code = get_code(101)
+print(code)
+```
+
+**Output:**
+```python
+def hello():
+    print("Hello from Code 101")
+```
+
+Both integer (`101`) and string (`"101"`, `"001"`) identifiers are supported.
+
+---
+
+## 8. Listing Codes
+
+List all registered code snippets:
+
+```python
+from mycodes import list_codes
+
+# Print formatted table
+list_codes()
+```
+
+**Output:**
+```text
+ID    NAME                 CATEGORY
+001   Hello World          Basics
+002   Addition             Math
+101   Greeting 101         Basics
+```
+
+To retrieve Python data instead of printing:
+```python
+codes = list_codes(return_data=True)
+for item in codes:
+    print(item["id"], item["name"])
+```
+
+---
+
+## 9. Searching
+
+Search across ID, name, description, category, and tags:
+
+```python
+from mycodes import search
+
+# Search by keyword
+search("binary")
+
+# Filter by category
+search(category="DSA")
+
+# Filter by language
+search(language="python")
+
+# Retrieve structured list
+results = search("sort", return_data=True)
+```
+
+---
+
+## 10. Jupyter Notebook Integration
+
+MyCodes includes custom IPython magic commands tailored for Jupyter:
+
+### Load Extension
+```python
+%load_ext mycodes
+```
+*(Alternatively, simply `import mycodes` in your notebook—it auto-registers magic commands!)*
+
+### Cell Injection: `%load_code`
+Type:
+```python
+%load_code 101
+```
+And execute the cell. Jupyter replaces `%load_code 101` with the actual code from your cloud library:
+```python
+def hello():
+    print("Hello from Code 101")
+```
+
+### Other Magic Commands
+- **`%code_info <id>`**: Displays snippet metadata.
+- **`%list_codes`**: Prints all snippets in your cloud library.
+- **`%search_code <query>`**: Searches for snippets by keyword.
+
+---
+
+## 11. Command Line Interface (CLI)
+
+Use `mycodes` directly in your terminal:
+
+```bash
+# List all codes
+mycodes list
+
+# Retrieve and print code
+mycodes get 101
+
+# Inspect metadata
+mycodes info 101
+
+# Search codes
+mycodes search binary
+
+# Update or inspect configuration
+mycodes config --username myusername
+```
+
+---
+
+## 12. Caching
+
+GitHub remains the authoritative source of truth. By default, code snippets are fetched fresh. You can enable local caching for offline or high-performance workflows:
+
+```python
+# Cache locally in ~/.mycodes/cache/
+code = get_code(101, cache=True)
+
+# Force refresh from GitHub, bypassing cache
+fresh_code = get_code(101, refresh=True)
+```
+
+The catalog `index.json` is cached in-memory for 5 minutes during active sessions to minimize unnecessary requests.
+
+---
+
+## 13. Security
+
+> ⚠️ **IMPORTANT SECURITY NOTICE:**
+> Executing remote code downloaded over the internet poses serious security risks.
+
+- `get_code()` **ONLY** retrieves the source code as text. It **never** executes remote code.
+- Remote execution is strictly opt-in via `run()`:
+  ```python
+  from mycodes import run
+
+  # This raises ExecutionDisabledError:
+  run(101)
+
+  # Explicit permission is required:
+  run(101, allow_execution=True)
+  ```
+- Only connect MyCodes to GitHub repositories that you own and trust.
+
+---
+
+## 14. Publishing to PyPI
+
+To build and publish `mycodes` to PyPI:
+
+1. **Install build and twine**:
+   ```bash
+   pip install --upgrade build twine
+   ```
+
+2. **Build distribution wheels**:
+   ```bash
+   python -m build
+   ```
+   This generates `dist/mycodes-0.1.0-py3-none-any.whl` and `dist/mycodes-0.1.0.tar.gz`.
+
+3. **Upload to TestPyPI (recommended first)**:
+   ```bash
+   python -m twine upload --repository testpypi dist/*
+   ```
+
+4. **Upload to Production PyPI**:
+   ```bash
+   python -m twine upload dist/*
+   ```
+
+---
+
+## 15. Installing on Another Computer
+
+On any new laptop, desktop, or cloud notebook:
+
+1. Install the package:
+   ```bash
+   pip install mycodes
+   ```
+
+2. Set your GitHub username once:
+   ```bash
+   mycodes config --username YOUR_GITHUB_USERNAME
+   ```
+
+3. Open Jupyter or Python and start loading your code:
+   ```python
+   from mycodes import get_code
+   print(get_code(101))
+   ```
+
+Zero manual file copying, zero local git repositories required!
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.