DOCSEARCHbyAlgolia
Submit Docs

Pyramid Web Framework

repository·main·Indexed 26 days ago

https://github.com/pylons/pyramid

The Pyramid Web Framework, a Pylons project (version 2.2.dev0). A flexible web framework providing tools for routing, request processing, and configuration. Key features include the Configurator for route patterns and default permissions, request attributes like matched_route and matchdict, and support for finished and response callbacks.

Tokens
151.3K
Snippets
321
Records
1.1K
Agent score
87%

What's inside pyramid

  1. Overview of Pyramid documentation structure

    main

    The Pyramid documentation is organized into four primary sections to support different learning and development needs:

    • Tutorials: Guided tours that build sample applications or implement specific concepts using a sample as a reference.
    • Narrative Documentation: Conversational descriptions of isolated Pyramid concepts, useful for deep dives or quick reminders.
    • API Documentation: A comprehensive, alphabetical reference of every public API exposed by Pyramid, organized by module name.
    • pscripts Documentation: Information regarding the p* scripts included with the Pyramid distribution.

  2. Overview of the Pyramid web framework

    main
    Pyramid is an open-source Python web application framework designed to simplify web development. It follows a minimalist philosophy where the core framework provides only essential tools: URL mapping to code, security, and serving static assets (e.g., JavaScript and CSS). Developers can extend the framework with additional tools for templating, database integration, and more, following a "pay only for what you eat" approach.

  4. Understand Pyramid's approach to configuration and module scope

    main

    Pyramid avoids common pitfalls found in microframeworks that rely on module-scope decorators to populate global registries. In many microframeworks, using decorators at the module level can lead to unintended side effects if the module is imported multiple times (e.g., by test runners or documentation tools), causing double-registration of routes or other configuration.

    Pyramid's configuration decorators are designed to mutate only the objects they are attached to (functions, classes, etc.) rather than an external global registry. This makes them safe even if a module is imported multiple times. For maximum predictability in large applications, Pyramid encourages imperative configuration using a Configurator object.

  5. Understand Traversal in Pyramid

    main
    Traversal is an alternative to URL dispatch in Pyramid. Instead of mapping specific URL patterns to code, traversal maps URLs to a resource tree. The URL space is defined by the keys within this tree. When a request is made, Pyramid traverses the tree starting from a root factory until it reaches a resource, which is then passed as the context argument to a view callable.

  6. Understand SQLAlchemy backend assumptions

    main

    When a project is generated using the sqlalchemy cookiecutter backend option, the following stack is configured:

    • Database: SQLite for persistent storage (though other SQL databases are supported).
    • ORM: SQLAlchemy for database access.
    • Migrations: Alembic for database migrations.
    • Data Loading: A console script for loading data.
    • Routing: URL dispatch to map URLs to code.
    • Transaction Management: zope.sqlalchemy, pyramid_tm, and transaction packages to scope database sessions to requests.

  7. Understand Pyramid Security and Permissions

    main

    Pyramid uses a permission-based security model:

    • permission: A string representing an action (e.g., read, view_blog_entries) checked against a context resource.
    • default permission: A permission registered for the entire application. If set, every view configuration is effectively amended to require this permission.
    • ACE (Access Control Entry): A three-tuple element within an ACL (Access Control List) that defines: (action, principal, permission).
      • action: Either Allow or Deny.
      • principal: A string describing a user or group.
      • permission: The specific permission being granted or denied.
      • Example: (Allow, 'bob', 'read') allows the principal 'bob' the 'read' permission.

  8. Understand Resource Tree and Traversal

    main

    Pyramid supports two main mechanisms for locating a context resource:

    • traversal: The act of descending a resource tree (a nested set of dictionary-like resource objects) from a root resource to find a specific context. The router performs traversal when a root factory is specified.
    • URL dispatch: An alternative to traversal that uses route configurations to locate a context resource.
    • resource: An object representing a node in the resource tree. In traversal, the resource becomes the context of a view. In URL dispatch, a single resource is generated per request to serve as the context.
    • location: The path to an object within a resource tree.

  9. Understand Pyramid Internationalization (i18n) concepts

    main

    Pyramid uses the GNU gettext library for internationalization. Key concepts include:

    • Locale Name: A string (e.g., en, en_US, de_AT) identifying a specific locale.
    • Localizer: An instance of pyramid.i18n.Localizer providing translation and pluralization services, retrieved via pyramid.i18n.get_localizer.
    • Locale Negotiator: An object that determines which locale name best represents a request. The pyramid.i18n.default_locale_negotiator is a standard example.
    • Translation Directory: A directory containing language folders, each with an LC_MESSAGES folder containing .mo files. The filename (without extension) is the translation domain.
    • Message Catalog: A .mo file containing translations.
    • Message Identifier: The string used as a lookup key (the msgid) during localization.

  10. Understand Pyramid's Request and Response objects

    main

    Pyramid's request and response implementations are based on the WebOb package.

    • The request object passed to a Pyramid view is an instance of pyramid.request.Request, which is a subclass of webob.request.Request.
    • The response object returned from a Pyramid view or renderer is an instance of pyramid.response.Response, which is a subclass of webob.response.Response.

    Users can return an instance of pyramid.response.Response directly from a view when needed. While Pyramid adds specific functionality to the standard WebOb request, most Pyramid users interact with these objects through the Pyramid API rather than using raw WebOb WSGI-related features.

  11. Understand View Configuration and View Lookup

    main
    In Pyramid, View lookup is the subsystem responsible for finding and invoking a view callable. View configuration is the mechanism used to control how this lookup operates. During a request, the view lookup subsystem compares the provided view configuration against the incoming request data to determine the most appropriate (the "best") view callable to execute.

  12. Understand Two-Phase Configuration in Pyramid

    main

    By default, Pyramid uses a non-autocommitting Configurator which executes configuration in two phases:

    1. Phase 1 (Eager Actions): Executes "eager" actions (like registering a renderer) and computes discriminators for all subsequent actions.
    2. Phase 2 (Conflict Detection): Compares discriminators to detect configuration conflicts.

    Key Implications:

    • Order Independence: For most configuration methods, the order of calls does not matter. For example, you can call add_view with a custom renderer before you have actually called add_renderer for that extension. The view will still find the renderer because of the two-phase process.
    • Internal Constraints: Some methods, like add_route, have internal ordering constraints (the order in which routes are defined matters) that are NOT affected by two-phase configuration.
    • Autocommitting Configurator Exception: If you use an autocommitting configurator, two-phase configuration is disabled. In this mode, you must order your configuration statements in dependency order (e.g., register the renderer before the view that uses it).