Skip to main content

Setting Up Local Development

To run etchblok-test-api locally, you use the DevelopmentConfig class, which is the default configuration for the application factory. This configuration enables debug mode and optimizes cache and pagination settings for a local environment.

Running the Application Locally​

The simplest way to start etchblok-test-api for development is using the run.py script. This script initializes the application with the default DevelopmentConfig and starts the Flask development server.

# run.py
from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run(debug=True, port=5000)

By default, create_app uses DevelopmentConfig from app/config.py:

# app/__init__.py
def create_app(config_class=DevelopmentConfig) -> Flask:
    app = Flask(__name__)
    app.config.from_object(config_class)
    # ...
    return app

Development Settings​

The DevelopmentConfig class in app/config.py provides several defaults tailored for local work:

  • DEBUG: Set to True to enable Flask's interactive debugger and reloader.
  • PAGE_SIZE: Set to 10 (reduced from the default 25) to make testing pagination easier with smaller datasets.
  • SECRET_KEY: Defaults to the string "change-me" if the SECRET_KEY environment variable is not set.
  • Cache Configuration: Provides a short TTL (30 seconds) and a small maximum size (128 entries) via get_cache_config().
# app/config.py
@dataclass
的应用 class DevelopmentConfig(BaseConfig):
    """Configuration for local development."""

    DEBUG: bool = True
    PAGE_SIZE: int = 10

    def get_cache_config(self) -> Dict[str, Any]:
        return _build_cache_config(ttl=30, max_size=128)

Customizing Local Settings​

You can customize your local environment by setting environment variables before running the application. For example, to use a specific secret key:

export SECRET_KEY="my-local-secret"
python run.py

If you need to programmatically override settings, you can create a custom configuration class that inherits from DevelopmentConfig and pass it to the factory:

from app import create_app
from app.config import DevelopmentConfig

class MyLocalConfig(DevelopmentConfig):
    PAGE_SIZE = 5

app = create_app(config_class=MyLocalConfig)

Troubleshooting and Limitations​

When working with local configuration in etchblok-test-api, be aware of the following implementation details:

  • Hardcoded Cache Size: The BookmarkService currently initializes its internal LRUCache with a hardcoded max_size=256, which overrides the max_size defined in DevelopmentConfig.get_cache_config().
  • Route Pagination Defaults: While DevelopmentConfig sets PAGE_SIZE to 10, the list_bookmarks route in app/routes/bookmarks.py currently defaults to 25 in its request handling logic: 
    # app/routes/bookmarks.py
    per_page = request.args.get("per_page", 25, type=int)
  • Secret Key Security: In DevelopmentConfig, the SECRET_KEY will fall back to "change-me". In contrast, ProductionConfig will raise a KeyError if the environment variable is missing, ensuring that insecure defaults are not used in production.