tessl/pypi-python-creole

A pure Python markup converter supporting creole2html, html2creole, html2ReSt, and html2textile conversions

—

Pending

Overview

Eval results

Files

Setup and Utilities

Name: tessl/pypi-python-creole
Author: tessl

Helper functions for project setup, README generation, and development workflows. These utilities are particularly useful for Python package development, enabling conversion from Creole markup to ReStructuredText for PyPI compatibility and automated documentation workflows.

Capabilities

README Management

Functions for converting and maintaining README files in multiple formats for package distribution.

def get_long_description(package_root: str, filename: str = 'README.creole', 
                        raise_errors: bool = None) -> str: ...
def update_rst_readme(package_root: str, filename: str = 'README.creole') -> None: ...
def assert_rst_readme(package_root: str, filename: str = 'README.creole') -> None: ...
def update_creole_rst_readme() -> None: ...

Usage Examples:

from creole.setup_utils import get_long_description, update_rst_readme, assert_rst_readme

# Convert README.creole to ReStructuredText for setup.py
long_desc = get_long_description('./my_package')
# Returns ReStructuredText version of README.creole content

# Update README.rst from README.creole
update_rst_readme('./my_package')
# Creates/updates README.rst file

# Validate README files are in sync (for testing)
assert_rst_readme('./my_package')
# Raises AssertionError if README.rst is out of date

# Update from command line (if using as entry point)
update_creole_rst_readme()
# Updates README.rst in current directory

Legacy README Conversion (Deprecated)

Convert Creole README to ReStructuredText for setup.py long_description.

def get_long_description(package_root: str, filename: str = 'README.creole', 
                        raise_errors: bool = None) -> str

Parameters:

package_root: Path to package root directory
filename: README filename (default: 'README.creole')
raise_errors: Whether to raise errors on conversion failure (auto-detected if None)

Returns: ReStructuredText string suitable for PyPI

Usage Examples:

# In setup.py (deprecated approach)
from creole.setup_utils import get_long_description
import warnings

# Suppress deprecation warning if needed
with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    long_description = get_long_description('.')

setup(
    name='my-package',
    long_description=long_description,
    long_description_content_type='text/x-rst',
    # ... other setup parameters
)

README Update Utilities

Modern utilities for maintaining synchronized README files.

def update_rst_readme(package_root: str, filename: str = 'README.creole') -> None

Parameters:

package_root: Path to package root directory
filename: Source Creole filename (default: 'README.creole')

Usage Examples:

from creole.setup_utils import update_rst_readme

# Update README.rst from README.creole
update_rst_readme('/path/to/my_package')

# Custom source filename
update_rst_readme('/path/to/my_package', 'docs/README.creole')

# Use in build scripts
import os
package_dir = os.path.dirname(__file__)
update_rst_readme(package_dir)

README Validation

Validate that ReStructuredText README is up-to-date with Creole source.

def assert_rst_readme(package_root: str, filename: str = 'README.creole') -> None

Parameters:

package_root: Path to package root directory
filename: Source Creole filename (default: 'README.creole')

Raises: AssertionError if README.rst is out of date or missing

Usage Examples:

from creole.setup_utils import assert_rst_readme
import unittest

class TestDocumentation(unittest.TestCase):
    def test_readme_is_current(self):
        """Ensure README.rst matches README.creole"""
        assert_rst_readme('.')
        
# In CI/build validation
try:
    assert_rst_readme('/project/root')
    print("README files are synchronized")
except AssertionError:
    print("ERROR: README.rst is out of date, run update_rst_readme()")
    exit(1)

Command Line Entry Point

Entry point for command-line README updates.

def update_creole_rst_readme() -> None

Usage Examples:

# Called by command line tool
# $ update_rst_readme
from creole.setup_utils import update_creole_rst_readme
update_creole_rst_readme()  # Updates README.rst in current directory

Error Handling Configuration

Utility for determining when to raise errors based on command line context.

def should_raise_errors() -> bool: ...

Returns: True if errors should be raised based on sys.argv analysis

Usage Examples:

from creole.setup_utils import should_raise_errors

# Automatically determine error handling
if should_raise_errors():
    # Running in build/check context, raise errors
    strict_mode = True
else:
    # Running in install context, be permissive
    strict_mode = False

Integration Patterns

Modern Setup.py Integration

# setup.py
from pathlib import Path
from creole.setup_utils import update_rst_readme

# Ensure README.rst is current
package_root = Path(__file__).parent
update_rst_readme(str(package_root))

# Read the updated file
readme_rst = (package_root / "README.rst").read_text(encoding='utf-8')

setup(
    name='my-package',
    long_description=readme_rst,
    long_description_content_type='text/x-rst',
    # ... other parameters
)

Poetry Integration

# In a build script called by poetry
from creole.setup_utils import update_rst_readme

def build_docs():
    update_rst_readme('.')
    print("README.rst updated from README.creole")

if __name__ == '__main__':
    build_docs()

CI/CD Validation

# In test suite or CI script
import unittest
from creole.setup_utils import assert_rst_readme

class DocumentationTests(unittest.TestCase):
    def test_readme_synchronization(self):
        """Verify README files are synchronized"""
        try:
            assert_rst_readme('.')
        except AssertionError:
            self.fail("README.rst is out of date. Run 'update_rst_readme' to fix.")

Makefile Integration

# build_readme.py
from creole.setup_utils import update_rst_readme
import sys

if __name__ == '__main__':
    package_root = sys.argv[1] if len(sys.argv) > 1 else '.'
    update_rst_readme(package_root)
    print(f"Updated README.rst in {package_root}")

# Makefile
update-readme:
    python build_readme.py

check-readme:
    python -c "from creole.setup_utils import assert_rst_readme; assert_rst_readme('.')"

.PHONY: update-readme check-readme

Constants

RAISE_ERRORS_ARGS: tuple = (
    'check', 'register', 'sdist', 'bdist', 'upload',
    '--long-description', '--restructuredtext'
)

Commands and arguments that indicate strict error handling should be enabled.

Error Handling

The utilities provide different error handling modes:

Strict mode: Enabled during package building, checking, and uploading
Permissive mode: Enabled during installation to avoid blocking package installation
Validation mode: Always raises errors for testing and CI environments

Conversion errors are handled gracefully in permissive mode by prefixing the original content with error information, ensuring package installation continues even with markup conversion issues.

Install with Tessl CLI