Skip to main content

Setting Up Your Development Environment

To set up your local development environment for the Pagemark API, you use the DevelopmentConfig class which provides optimized settings for debugging and local caching.

Running the Development Server​

The simplest way to start the API locally is to execute the run.py script. This script initializes the application using the default development settings 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() in app/__init__.py uses DevelopmentConfig as its configuration class:

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

Development Configuration Settings​

The DevelopmentConfig class in app/config.py overrides several defaults from BaseConfig to facilitate easier local testing and debugging.

# 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)

Key features of this configuration include:

  • DEBUG Mode: Set to True, enabling Flask's interactive debugger and automatic reloading.
  • Reduced Page Size: The PAGE_SIZE is reduced to 10 (from the default 25) to make testing pagination easier with smaller datasets.
  • Short-lived Cache: The get_cache_config() method returns a configuration with a 30-second TTL and a maximum of 128 entries, ensuring that local changes are reflected quickly.

Overriding Environment Variables​

Even in development, you may need to override certain sensitive settings like the SECRET_KEY. The BaseConfig class (which DevelopmentConfig inherits from) attempts to read this from the environment:

# app/config.py
@dataclass
class BaseConfig:
    SECRET_KEY: str = field(default_factory=lambda: os.environ.get("SECRET_KEY", "change-me"))
    # ...

To use a custom key locally, export the variable before running the server:

export SECRET_KEY='your-custom-dev-key'
python run.py

Troubleshooting and Limitations​

When working in the development environment, be aware of the following implementation details in the current codebase:

  • Hardcoded Cache Size: Although DevelopmentConfig.get_cache_config() specifies a max_size of 128, the BookmarkService currently initializes its LRUCache with a hardcoded value of 256 in app/services/bookmark_service.py: 
    def _init_services(self) -> None:
        self._repo = BookmarkRepository()
        self._cache: LRUCache[Bookmark] = LRUCache(max_size=256) # Ignores config
        self._search = SearchIndex(self._repo)
  • Pagination Defaults: The PAGE_SIZE of 10 defined in DevelopmentConfig is not automatically applied to service methods. For example, BookmarkService.list_bookmarks defaults to 25 unless the configuration value is explicitly passed from the route handler: 
    def list_bookmarks(
        self, page: int = 1, per_page: int = 25, status: Optional[str] = None
    ) -> Tuple[List[Bookmark], int]:
        # ...