AGENTS.md · pyecharts/pyecharts

Sections

1. Build/Lint/Test Commands
2. Code Style Guidelines
3. Development Workflow
4. Additional Notes

First lines (shown under the repo's MIT license)

# AGENTS.md

This file contains guidelines for agents working on the pyecharts project.

## Build/Lint/Test Commands

### Running Tests

The project uses multiple testing frameworks. Here are the commands to run tests:

1. **Run all tests**:
   ```bash
   make test
   # or
   python test.py
   # or
   nose2 --with-coverage --coverage pyecharts --coverage-config .coveragerc -s test
   # or
   pytest -cov-config=.coveragerc --cov=./ test/
   ```

2. **Run a single test file**:
   ```bash
   # Using pytest (recommended)
   pytest test/test_chart.py
   
   # Using nose2
   nose2 --with-coverage --coverage pyecharts --coverage-config .coveragerc test.test_chart
   ```

3. **Run a specific test method**:
   ```bash
   # Using pytest
   pytest test/test_chart.py::TestChartClass::test_chart_dark_mode
   
   # Using nose2
   nose2 --with-coverage --coverage pyecharts --coverage-config .coveragerc test.test_chart.TestChartClass.test_chart_dark_mode
   ```

4. **Run tests with verbose output**:
   ```bash
   pytest -v test/test_chart.py
   ```

5. **Run tests with coverage reporting**:
   ```bash
   pytest -v --cov=./ --cov-report=html test/test_chart.py
   ```

### Linting

1. **Run linter**:
   ```bash
   make lint
   # or
   flake8 --exclude=build,images,example,examples --max-line-length=89 --ignore=F401
   ```

2. **Lint a specific file**:
   ```bash
   flake8 --exclude=build,images,example,examples --max-line-length=89 --ignore=F401 test/test_chart.py
   ```

### Formatting

The project uses black and isort for code formatting:

1. **Run black formatter**:
   ```bash
   black .
   ```

2. **Run isort for imports**:
   ```bash
   isort .
   ```

### Building

1. **Build the package**:
   ```bash
   python setup.py sdist bdist_wheel
   ```

2. **Upload to PyPI**:
   ```bash
   make upload
   # This runs the UploadCommand defined in setup.py
   ```

## Code Style Guidelines

### Imports

1. **Import organization**:
   - Standard library imports
   - Related third party imports
   - Local application/library specific imports

2. **Import style**:
   ```python
   # Good
   from pyecharts import options as opts
   from pyecharts.charts import Line, Bar
   
   # Avoid
   from pyecharts.options import *
   import pyecharts.charts.Line
   ```

3. **Use aliases** for commonly used modules:
   ```python
   import pyecharts.options as opts
   import pyecharts.globals as globals
   ```

### Formatting

1. **Line length**: 89 characters max (as specified in flake8 command)

2. **Indentation**: 4 spaces (no tabs)

3. **Quotes**: Use double quotes " for strings, single quotes ' for char literals

4. **Blank lines**:
   - Top-level functions and classes: 2 blank lines
   - Methods within a class: 1 blank line

5. **Use black formatter** to ensure consistent code style

### Naming Conventions

1. **Variables and functions**: snake_case
   ```python
   def add_yaxis(self, series_name, y_axis, *args, **kwargs):
       pass
   ```

2. **Classes**: PascalCase
   ```python
   class TestChartClass(unittest.TestCase):
       pass
   ```

3. **Constants**: UPPER_CASE
   ```python
   MAX_RETRIES = 3
   ```

4. **Private members**: prefix with _
   ```python
   def _internal_method(self):
       pass
   ```

### Error Handling

1. **Use exceptions** for error conditions, not return codes

2. **Be specific** with exception types: