Changeset 38

Show
Ignore:
Timestamp:
02/08/07 21:50:29 (6 years ago)
Author:
cleverdevil
Message:

More improvements to the docstrings for the generated documentation. This time, for the fields module.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • elixir/trunk/elixir/fields.py

    r33 r38  
     1''' 
     2====== 
     3Fields 
     4====== 
     5 
     6This module contains DSL statements which allow you to declare which  
     7fields (columns) your Elixir entities have.  There are currently two 
     8different statements that you can use to declare fields: 
     9 
     10 
     11`has_field` 
     12----------- 
     13The `has_field` statement allows you to define fields one at a time. 
     14 
     15The first argument is the name of the field, the second is its type, and 
     16following this any number of keyword arguments can be specified for 
     17additional behavior. The keyword arguments are passed on to the SQLAlchemy 
     18``Column`` object. Please refer to the SQLAlchemy ``Column`` object's 
     19documentation for further detail about which keyword arguments are 
     20supported. 
     21 
     22Here is a quick example of how to use ``has_field``. 
     23 
     24:: 
     25 
     26    class Person(Entity): 
     27        has_field('id', Integer, primary_key=True) 
     28        has_field('name', String(50)) 
     29 
     30 
     31`with_fields` 
     32------------- 
     33The `with_fields` statement allows you to define fields all at once. 
     34 
     35Each keyword argument to this statement represents one field, which should 
     36be a `Field` object. The first argument to a Field object is its type, and 
     37following this any number of keyword arguments can be specified for 
     38additional behavior. The keyword arguments are passed on to the SQLAlchemy 
     39``Column`` object. Please refer to the SQLAlchemy ``Column`` object's 
     40documentation for further detail about which keyword arguments are 
     41supported. 
     42 
     43Here is a quick example of how to use ``with_fields``. 
     44 
     45:: 
     46 
     47    class Person(Entity): 
     48        with_fields( 
     49            id = Field(Integer, primary_key=True), 
     50            name = Field(String(50)) 
     51        ) 
     52''' 
     53 
    154from sqlalchemy             import Column 
    255from elixir.statements      import Statement 
    … …  
    457__all__ = ['has_field', 'with_fields', 'Field'] 
    558 
    6 __pudge_all__ = __all__ 
     59__pudge_all__ = ['Field'] 
    760 
    861class Field(object): 
    … …  
    1164     
    1265    This class represents a column on the table where the entity is stored. 
    13     This object is only used with the ``with_fields`` syntax for defining all 
    14     fields for an entity at the same time. The ``has_field`` syntax does not 
     66    This object is only used with the `with_fields` syntax for defining all 
     67    fields for an entity at the same time. The `has_field` syntax does not 
    1568    require the manual creation of this object. 
    1669    ''' 
    … …  
    3992 
    4093class HasField(object): 
    41     ''' 
    42     Statement object for specifying a single field on an entity. 
    43      
    44     The first argument is the name of the field, the second is its type, and 
    45     following this any number of keyword arguments can be specified for 
    46     additional behavior. The keyword arguments are passed on to the SQLAlchemy 
    47     ``Column`` object. Please refer to the SQLAlchemy ``Column`` object's 
    48     documentation for further detail about which keyword arguments are 
    49     supported. 
    50      
    51     Here is a quick example of how to use ``has_field``. 
    52      
    53     :: 
    54      
    55         class Person(Entity): 
    56             has_field('id', Integer, primary_key=True) 
    57             has_field('name', String(50)) 
    58     ''' 
    59      
    6094    def __init__(self, entity, name, *args, **kwargs): 
    6195        field = Field(*args, **kwargs) 
    … …  
    6599 
    66100class WithFields(object): 
    67     ''' 
    68     Statement object for specifying all fields on an entity at once. 
    69      
    70     Each keyword argument to this statement represents one field, which should 
    71     be a Field object. The first argument to a Field object is its type, and 
    72     following this any number of keyword arguments can be specified for 
    73     additional behavior. The keyword arguments are passed on to the SQLAlchemy 
    74     ``Column`` object. Please refer to the SQLAlchemy ``Column`` object's 
    75     documentation for further detail about which keyword arguments are 
    76     supported. 
    77      
    78     Here is a quick example of how to use ``with_fields``. 
    79      
    80     :: 
    81      
    82         class Person(Entity): 
    83             with_fields( 
    84                 id = Field(Integer, primary_key=True), 
    85                 name = Field(String(50)) 
    86             ) 
    87     ''' 
    88      
    89101    def __init__(self, entity, *args, **fields): 
    90102        columns = list()