Configuring for Development

To configure the application for local development, use the DevelopmentConfig class. This configuration is the default for the application factory and provides settings optimized for debugging and rapid iteration.

Using the Development Configuration

By default, calling create_app() without arguments uses DevelopmentConfig. This is the pattern used in the project's entry point, run.py.

# run.py
from app import create_app

# create_app defaults to DevelopmentConfig
app = create_app()

if __name__ == "__main__":
    # Explicitly enabling debug mode for the Flask development server
    app.run(debug=True, port=5000)

The create_app factory in app/__init__.py loads the configuration using Flask's from_object method:

# app/__init__.py
from app.config import DevelopmentConfig

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

Key Development Settings

The DevelopmentConfig class in app/config.py overrides several defaults from BaseConfig to facilitate local work:

Setting	Value	Description
DEBUG	True	Enables Flask's debug mode, providing an interactive debugger in the browser on errors.
PAGE_SIZE	10	Reduces the default number of items per page (from the global default of 25) to make testing pagination easier with small datasets.
SECRET_KEY	"change-me"	Defaults to a placeholder string if the SECRET_KEY environment variable is not set.

Cache Configuration

The get_cache_config() method provides a more aggressive eviction policy for development to ensure changes are reflected quickly:

# app/config.py
@dataclass
class DevelopmentConfig(BaseConfig):
    # ...
    def get_cache_config(self) -> Dict[str, Any]:
        # Shorter TTL (30s) and smaller size (128) than production
        return _build_cache_config(ttl=30, max_size=128)

Customizing Local Settings

If you need to override specific settings without modifying the core codebase, you can use environment variables or create a local subclass.

Using Environment Variables

The SECRET_KEY is automatically pulled from the environment if available:

export SECRET_KEY="your-local-secret-key"
python run.py

Creating a Custom Local Config

For more complex overrides, you can subclass DevelopmentConfig and pass it to the factory:

# local_run.py
from app import create_app
from app.config import DevelopmentConfig
from dataclasses import dataclass

@dataclass
class LocalConfig(DevelopmentConfig):
    PAGE_SIZE: int = 5
    MY_CUSTOM_SETTING: str = "custom-value"

app = create_app(config_class=LocalConfig)

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

Troubleshooting

Cache Size Inconsistency

Note that while DevelopmentConfig.get_cache_config() specifies a max_size of 128, the BookmarkService currently hardcodes its internal LRUCache size to 256 in its initialization:

# app/services/bookmark_service.py
def _init_services(self) -> None:
    self._repo = BookmarkRepository()
    # This ignores the config class setting
    self._cache: LRUCache[Bookmark] = LRUCache(max_size=256)
    self._search = SearchIndex(self._repo)

Redundant Debug Flags

The run.py script passes debug=True directly to app.run(). This will enable the Flask debugger even if DevelopmentConfig.DEBUG is manually set to False within the config class. To strictly follow the config class, use app.run(debug=app.config['DEBUG']).