Using Pybald

A Quick Note on Naming Conventions

Pybald tries to bridge the convention over configuration (CoC) approach and the explicit approach to creating a web application. For the basics of the web framework, it tends to favor the CoC approach. Pybald has a few naming conventions that are expected and may cause confusion if not understood.

Naming Controllers

Controllers are implemented as Python classes and are therefore expected to follow the PEP8 naming standard and be named in the StudlyCaps format (otherwise known as CamelCase). Additionally, while not strictly required, controller names usually contain the suffix Controller (e.g. UserProfileController).

When the pybald route map is generated, the controller class name is converted to underscore_separated format and ‘_controller’ is stripped if present. Following the example above, the route map would contain the identifier user_profile for the controller. When creating connections in the url mapping, the controller identifier would be used for the controller argument.

Naming Models

Models are also implemented as Python classes and are expected to follow the PEP8 style guide and be named in the StudlyCaps style. Model class names are usually expected to be singular nouns (User not Users).

When pybald models are synchronized with a databse, by default the underlying tables are named by converting the StudlyCaps class name into an underscore_separated form and pluralized. Therefore a UserProfile model will (by default) create a user_profiles database table. Obviously an explicit table name can also be provided to any model to override this default behavior.

Naming Modules

All modules are expected to also follow the PEP8 style guide and be named in the underscore_separated style.

Structure of a Pybald Application

A Pybald application is configured, at least partially, by the directory structure of the project. While a Pybald application can consist of a single file, as a project grows it’s useful to organize the code into a specific directory structure. The following is the recommended structure for larger projects.

./app
This is the primary application directory containing the controllers, views and models
./app/controllers
All controller files for the project
./app/models
Models for the project
./app/middleware
optional - Any project specific WSGI middleware
./app/views
Templates for the project
./app/urls.py
Url patterns to match against
./public
Static content like images, css and javascript
./project.py
optional - configuration file for the project.
./environment.py
optional - local, environment-specific, configuration overrides (e.g. Production, Development, Test)
./config
Web server configuration, startup scripts.
./utilities
Project utility scripts.
./tmp
Temporary files
./viewscache
temporary The template engine’s file cache for views

Most of your application code will be in the app directory which should contain at least these three directories controllers, views, and models.

A Pybald application consists of the following parts:

  • A webserver
  • A WSGI pipeline
  • A Router/Dispatcher WSGI module
  • User defined controllers, models, and views
  • Any additional WSGI middleware
  • Static content: images, css, javascript

The heart of a Pybald application is the WSGI pipeline. The pipeline is defined in the main application file which is usually the name of the project + ‘.py’ (i.e. ./sample_app.py). The WSGI pipeline is your application as well as how your webserver of choice will communicate with your application. The exposed app can be used to connect to any WSGI compliant webserver (Apache, nginx, uWSGI, etc…).

# The main application pipeline
# Include all WSGI middleware here. The order of
# web transaction will flow from the bottom of this list
# to the top, and then back out. The pybald Router
# should usually be the first item listed.
# ----------------------------------
app = Router(routes=my_project.app.urls.map)
# app = UserManager(app, user_class=User)
# app = SessionManager(app, session_class=Session)
# app = ErrorMiddleware(app, error_controller=None)
# app = DbMiddleware(app)
# ----------------------------------
#    ↑↑↑                  ↓↓↓
#    ↑↑↑                  ↓↓↓
#   Request              Response

Invoking the development web server from the command line should look similar to starting the console (in fact the same code executes). The webserver log is dumped to the console so you can monitor transactions.

~/test_project$ python sample_app.py serve
Route name Methods Path
home               /
base               /{controller}/{action}/{id}
                   /{controller}/{action}
                   /{controller}
                   /*(url)/
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080

The Pybald console

The pybald console allows you to interact with your program using the python REPL.

The console automatically loads the route mapping for your application as well as all of the models for your project. The console allows you to interact with your application directly, experiment with new functionality, play with models, and test and exercise the application.

It also includes a command history per-project.