----------------------------------------------------------------------
This is the API documentation for the positron_codetyper library.
----------------------------------------------------------------------


## Configuration

Configuration dataclasses and schema


Config(language: Literal['r', 'python', 'quarto'], output_file: str, typing_speed: float = 0.05, execute_blocks: bool = True, pause_between_blocks: float = 2.0, blocks: List[positron_codetyper.config.CodeBlock] = None, frontmatter: Optional[str] = None, mode: Literal['terminal', 'ide'] = 'terminal', ide_path: Optional[str] = None, format_output: bool = False, record: bool = False, record_device: Optional[str] = None, record_output: str = 'recording.mp4') -> None

Main configuration for CodeTyper.

This configuration controls all aspects of how CodeTyper types and
executes your code. Created by parsing script files with YAML frontmatter.

Parameters
----------
language : Literal['r', 'python', 'quarto']
    Programming language of the code
output_file : str
    Path where typed code will be saved
typing_speed : float
    Seconds to wait between typing each character (default: 0.05)
execute_blocks : bool
    Whether to execute code after typing in terminal mode (default: True)
pause_between_blocks : float
    Seconds to pause between blocks (default: 2.0)
blocks : List[CodeBlock]
    List of code blocks to type
frontmatter : Optional[str]
    Raw frontmatter text (for Quarto files)
mode : Literal['terminal', 'ide']
    Typing mode: 'terminal' or 'ide' (default: 'terminal')
ide_path : Optional[str]
    Custom path to Positron.app (if not using default location)
format_output : bool
    Whether to format output with Ruff/styler after typing (default: False)

Examples
--------
>>> config = Config(
...     language='python',
...     output_file='demo.py',
...     typing_speed=0.05,
...     blocks=[...]
... )

CodeBlock(name: str, code: str, description: Optional[str] = None, execute: bool = True, pause_after: float = 1.0, type: Literal['code', 'markdown'] = 'code', language: Optional[str] = None) -> None

Represents a single code block to be typed.

A code block corresponds to a section marked with `##` headers in
your script file. Each block can have its own execution and timing settings.

Parameters
----------
name : str
    Display name of the block (from the `##` header)
code : str
    The actual code content to type
description : Optional[str]
    Optional description (not currently used)
execute : bool
    Whether to execute this block after typing (default: True)
pause_after : float
    Seconds to pause after typing this block (default: 1.0)
type : Literal['code', 'markdown']
    Block type (default: 'code')
language : Optional[str]
    Language for this specific block (if different from main config)

Examples
--------
>>> block = CodeBlock(
...     name="Import libraries",
...     code="import pandas as pd",
...     execute=True,
...     pause_after=1.5
... )


## Exceptions

Custom exception classes


CodeTyperError

Base exception for all CodeTyper errors.

All CodeTyper-specific exceptions inherit from this class,
making it easy to catch any CodeTyper error.

Examples
--------
>>> try:
...     # CodeTyper operations
...     pass
... except CodeTyperError as e:
...     print(f"CodeTyper error: {e}")

ConfigurationError

Raised when there are configuration or parsing errors.

This includes:
- Invalid YAML frontmatter
- Missing required configuration fields
- Invalid file formats
- Unsupported file types

Examples
--------
>>> raise ConfigurationError("Invalid YAML frontmatter")

ExecutionError

Raised when code execution or IDE operations fail.

This includes:
- Code execution failures
- Positron IDE access issues
- Missing accessibility permissions
- File write errors

Examples
--------
>>> raise ExecutionError("Failed to open Positron IDE")


----------------------------------------------------------------------
This is the User Guide documentation for the package.
----------------------------------------------------------------------

## Quick Install

Install CodeTyper using pip:

```bash
pip install -e .
```

This installs codetyper in editable mode from the local directory.

## Requirements

- **Python**: >= 3.8
- **Dependencies**:
  - rich >= 13.0.0
  - PyYAML >= 6.0
  - typer >= 0.9.0

## Verify Installation

After installation, verify the command is available:

```bash
codetyper --help
```

You should see the help message with available commands.

## Optional Dependencies

### For Code Formatting

**Python formatting** (with Ruff):
```bash
pip install ruff
```

**R formatting** (with styler):
```r
install.packages("styler")
```

### For IDE Mode (macOS only)

IDE mode requires:
- Positron IDE installed at `/Applications/Positron.app` (or custom path)
- macOS Accessibility permissions for your terminal

See the [IDE Mode guide](ide-mode.qmd) for setup instructions.

## Development Installation

For contributing to CodeTyper:

```bash
git clone https://github.com/yourusername/codetyper.git
cd codetyper
pip install -e .
```

## Troubleshooting

### Command not found

If `codetyper` command is not found after installation:

1. Check that the package is installed:
   ```bash
   pip list | grep codetyper
   ```

2. Check your Python scripts path is in PATH:
   ```bash
   python -m site --user-base
   ```

3. Try running as a module:
   ```bash
   python -m codetyper --help
   ```

### Permission errors

If you get permission errors during installation:

```bash
pip install --user -e .
```

Or use a virtual environment:

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
```


### Quick Start

Get started with CodeTyper in 5 minutes.

## 1. Create a Template

Generate a template script for your language:

```bash
# For Python
codetyper init python -o my_tutorial.py

# For R
codetyper init r -o my_tutorial.R
```

## 2. Edit Your Script

Open the generated file in your editor. It has this structure:

```python
---
language: python
output_file: demo.py
typing_speed: 0.05
execute_blocks: true
---

## Import libraries
import pandas as pd
import numpy as np

## Load data | pause_after=1.5
data = {'x': range(1, 11), 'y': np.random.randn(10)}
df = pd.DataFrame(data)

## Display results | execute=true, pause_after=2.0
print(df)
```

**Key components:**

- **YAML frontmatter** (between `---`): Configuration settings
- **`##` headers**: Mark code blocks
- **`|` settings**: Optional per-block configuration

## 3. Test Run

Run your script in terminal mode:

```bash
codetyper type-code my_tutorial.py
```

### Keyboard Controls

While typing (terminal mode only):

- **SPACE**: Pause/resume
- **↑**: Speed up (1.5x → 2x → 3x)
- **↓**: Slow down (0.75x → 0.5x)
- **→**: Skip current block
- **Q or ESC**: Quit

## 4. Record Your Tutorial

1. Open your screen recording software (QuickTime, OBS, etc.)
2. Start recording
3. Run: `codetyper type-code my_tutorial.py`
4. Watch the typing happen!

## IDE Mode

Type directly into Positron IDE:

```bash
codetyper type-code my_tutorial.py --ide
```

**Requirements:** macOS with accessibility permissions enabled.

## Common Options

### Faster typing
```bash
codetyper type-code my_tutorial.py --speed 0.02
```

### With formatting
```bash
codetyper type-code my_tutorial.py --format
```

### Custom output location
```bash
codetyper type-code my_tutorial.py -o output.py
```

### No execution (terminal mode)
```bash
codetyper type-code my_tutorial.py --no-execute
```

## Next Steps

- [Script format guide](script-format.qmd) - Learn all configuration options
- [IDE mode setup](ide-mode.qmd) - Configure Positron integration
- [Examples](examples.qmd) - See example scripts


### Script Format

CodeTyper uses R or Python scripts with YAML frontmatter and markdown headers.

## Basic Structure

```python
---
language: python
output_file: demo.py
typing_speed: 0.05
execute_blocks: true
---

## Block 1
code here

## Block 2 | execute=false, pause_after=2.0
more code
```

## Frontmatter Options

All available configuration options:

```yaml
---
# Required
language: python           # or 'r'
output_file: demo.py      # Where to save typed code

# Optional
typing_speed: 0.05        # Seconds per character (default: 0.05)
execute_blocks: true      # Run code after typing (default: true)
mode: terminal            # 'terminal' or 'ide' (default: terminal)
format_output: false      # Format with Ruff/styler (default: false)
ide_path: /path/to/Positron.app  # Custom Positron path
---
```

### Language

**Required.** Specifies the language:
- `python` - Python code
- `r` - R code

Can be auto-detected from file extension if omitted.

### Output File

**Required.** Path where the typed code will be saved.

### Typing Speed

Seconds to wait between each character. Default: `0.05`

- Slower: `0.1` (more dramatic)
- Normal: `0.05` (default)
- Faster: `0.02` (for quick demos)

Can be overridden with `--speed` flag.

### Execute Blocks

Whether to execute code blocks after typing (terminal mode only).

Default: `true`

Can be disabled with `--no-execute` flag.

### Mode

Typing mode:
- `terminal` - Type in terminal with syntax highlighting
- `ide` - Type into Positron IDE

Can be set with `--ide` flag.

### Format Output

Auto-format the output file after typing:
- Python: Uses Ruff
- R: Uses styler package

Can be enabled with `--format` flag.

## Code Blocks

Organize code into blocks with `##` headers:

```python
## Block Name
code here
```

### Block Names

The text after `##` becomes the block name:

```python
## Setup
## Load data
## Process and visualize
```

Block names are displayed during typing but not included in the output file.

## Block Settings

Add settings to blocks with the pipe `|` syntax:

```python
## Block Name | setting=value, setting2=value2
```

### Available Settings

**execute** (true/false)

Whether to execute this specific block:

```python
## Plots | execute=false
# Skip execution for plot code
```

**pause_after** (float)

Seconds to pause after typing this block:

```python
## Important step | pause_after=3.0
# Pause 3 seconds after typing
```

### Multiple Settings

Combine settings with commas:

```python
## Visualization | execute=false, pause_after=2.0
```

## Complete Example

### Python

```python
---
language: python
output_file: demo.py
typing_speed: 0.05
execute_blocks: true
format_output: true
---

## Import libraries
import pandas as pd
from plotnine import ggplot, aes, geom_line

## Load data | pause_after=1.5
df = pd.read_csv('data.csv')
print(f"Loaded {len(df)} rows")

## Create plot | execute=false, pause_after=2.0
(ggplot(df, aes('x', 'y')) + geom_line())
```

### R

```r
---
language: r
output_file: demo.R
typing_speed: 0.05
execute_blocks: true
---

## Setup
library(ggplot2)
library(dplyr)

## Load and process | pause_after=2.0
data <- read_csv('data.csv') %>%
  filter(!is.na(value))

## Visualize | execute=false
ggplot(data, aes(x, y)) + geom_line()
```

## Tips

1. **Use descriptive block names** - They help organize your tutorial
2. **Set execute=false for plots** - Plots may not display well in terminal
3. **Adjust pause_after** - Give viewers time to read important code
4. **Test before recording** - Run through once to check timing
5. **Use formatting** - `format_output: true` for clean output code