# YepCode Python Code Rules

> This file provides guidelines for LLMs to write Python code compatible with YepCode platform and ready to use its specific helpers.

This file provides guidelines for LLMs to write Python code compatible with YepCode platform and ready to use its specific helpers.

[Download this file](/docs/ai-rules/code/python.md)

## Python Code Rules

[Section titled “Python Code Rules”](#python-code-rules)

## Quick Reference

[Section titled “Quick Reference”](#quick-reference)

| Aspect                  | Guideline                              |
| ----------------------- | -------------------------------------- |
| **Runtime**             | Python 3.13                            |
| **Main file (process)** | `main.py`                              |
| **Entry point**         | `def main()`                           |
| **Parameters**          | `yepcode.context.parameters`           |
| **Variables**           | `os.getenv("X")` or `yepcode.env.X`    |
| **Modules**             | `yepcode.import_module("module-slug")` |

### Critical Rules

[Section titled “Critical Rules”](#critical-rules)

* ✅ **Always** define a `main()` function
* ❌ **Never** call `main()` directly
* ✅ **Always** add `try/except` around the main flow for actionable errors
* ✅ Follow **PEP 8** (and add type hints when useful)
* ✅ **Always** use **snake\_case** for variables and functions
* ❌ **Never** use dynamic module names with `yepcode.import_module()`—module names must be **hardcoded strings** (e.g. `yepcode.import_module("module-name")`), not variables

## Process Template

[Section titled “Process Template”](#process-template)

```python
def main():
    # Access input parameters
    parameters = yepcode.context.parameters


    # Your code here


    # Return result
    return { "message": "Success!" }
```

## Helpers Usage

[Section titled “Helpers Usage”](#helpers-usage)

* Access execution info: `execution_id = yepcode.execution.id`
* Access process info: `process_id = yepcode.execution.process.id`
* Access schedule info (if present): `scheduleId, scheduleComment = yepcode.execution.schedule.id, yepcode.execution.schedule.comment`
* Access team timezone: `timezone = yepcode.execution.timezone`
* Use environment variables: `api_key = os.getenv("API_KEY") # or yepcode.env.API_KEY`
* Import YepCode modules: `client = yepcode.import_module("module-name")`
  * Caution: module names must be **hardcoded strings** (no variables)
* Import with version: `client = yepcode.import_module("module-name", "v1.0")`
* Run another process: `yepcode.processes.run("process-identifier", options)`

## Logging

[Section titled “Logging”](#logging)

```python
print("INFO message")  # Generates INFO level log
logger.debug("DEBUG message")
logger.info("INFO message")
logger.warn("WARNING message")
logger.error("ERROR message")
```

## Dependencies Management

[Section titled “Dependencies Management”](#dependencies-management)

* You may use external pip packages.
* Just add the `import` statement and the package will be installed automatically.
* If the **package name** differs from the **import name**, use the `@add-package` comment:

```python
# @add-package requests
import requests
```

## Local Disk

[Section titled “Local Disk”](#local-disk)

```python
import os


# Calculate the path to the temporary file
file_path = os.path.join(os.environ.get("TMP_DATA_DIR"), "myfile.txt")


# Writing a file
with open(file_path, 'w') as f:
    f.write('Hello from YepCode!')
```

## Datastore

[Section titled “Datastore”](#datastore)

```python
import json


# Setting a value
yepcode.datastore.set("key", "value")


# Setting a object value
yepcode.datastore.set("key", json.dumps({ "name": "John", "age": 30 }))


# Getting a value
value = yepcode.datastore.get("key")


# Deleting a value
yepcode.datastore.delete("key")
```

## Storage

[Section titled “Storage”](#storage)

```python
import os
local_path = os.path.join(os.environ.get("TMP_DATA_DIR"), "localfile.txt")


# Uploading a file
with open(local_path, "rb") as f:
    obj = yepcode.storage.upload("path/myfile.txt", f)
    print("Uploaded:", obj.name, obj.size, obj.link)




# Listing files
objects = yepcode.storage.list()


# Downloading a file
content = yepcode.storage.download("path/myfile.txt")
with open(local_path, "wb") as f:
    f.write(content)


# Deleting a file
yepcode.storage.delete("path/myfile.txt")
```

## Return Values

[Section titled “Return Values”](#return-values)

### Standard Return

[Section titled “Standard Return”](#standard-return)

```python
return { "message": "Success!" }
```

### Custom HTTP Status Codes

[Section titled “Custom HTTP Status Codes”](#custom-http-status-codes)

* This is the format for custom HTTP status codes:

```python
return {
    "status": 404,
    "body": { "message": "Not found" },
    "headers": { "Content-Type": "application/json" }
}
```

## Transient Results

[Section titled “Transient Results”](#transient-results)

```python
return {
    "transient": True,
    "data": sensitive_data
}
```

## Do & Don’t

[Section titled “Do & Don’t”](#do--dont)

**Do**

* Define `main()` and avoid calling it directly.
* Validate parameters at the start; raise meaningful errors for missing or invalid input.
* Use environment variables (e.g. `os.getenv("API_KEY")`) for secrets; never hardcode them.
* Use try/except around the main flow and log or re-raise with clear messages.
* Use **snake\_case** for variables and functions; follow PEP 8.
* Use type hints where helpful.
* Log important steps; never log secrets.

**Don’t**

* Never call `main()` in your code—YepCode invokes it.
* Never hardcode API keys, passwords, or tokens.
* Don’t use **camelCase** in Python; use snake\_case.
* Don’t ignore errors; wrap risky operations in try/except.
* Don’t use dynamic module names: `yepcode.import_module(module_name)` is wrong; use `yepcode.import_module("module-name")`.
* Don’t rely on global variables for state; pass state through parameters or return values.