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.
