web_utils 0.0.5

web_utils collection that used in web development process.

Web Utils
------------

Web development utils classes and functions.
Current status: Under development and works in my project.
Find me in http://github.com/winkidney/web_utils.

Summaries are listed below.Documents will be written later.

##Install
```
pip install "web_utils[forms,security,sqlalchemy]" # to install all requirements.
```

##Summaries

+ code_loader - load code from str or unicode object and save it to cache or database
+ forms - some custom validator for wtfomrs
+ json_form - wrapper for jsonschema to validate json string like wtfomrs.
+ Security - password generator by bcrypt.Simple url sign generator.
+ _sqlalchemy - DBFieldConverter for convert alchemy's model instance to dict like string with white list support.
+ _pyramid - tools form pyramid web framework
+ extra - some other utils.


##web_utils.code_loader

Create a Code loader instance to load and save code from Storage or str object.
Return a python module object that you can run any code within it.

+ Methods
+ __init__(name, storage_backend=DummyStorageBackend, cache_backend=DummyCacheBackend)
Create a loader with given storage_backend and cache_backend.
+ create_module(fullname, code_script, save_key=None)
if `save_key` is given, use it instead of fullname as `accees_key` passed to storage backend's `set` method.
+ save(mod, cached=False, **kwargs)
save a module object into storage backend and cache backend(optional).
**kwargs will be passed to backend's `set` method.
+ load(fullname, save_key=None, **kwargs)
Load a module by its name(if `save_key` is given, use it instead).

##web_utils.forms
WTFroms's custom field and other validator

+ validators
+ uuid_validator
+ TimeAfterNow validator - return `True` if current datetime-field later than now.
+ MobilePhone validataor - Check if a number sequence is china's phone number
+ custom field
+ UnixTimeField
+ TextArrayField - convert `list` like `a, b, c ,1 ,3 ,3` to python list.
+ JsonField - Check if the text is json format string and convert it into python data(with `json.loads`)
+ IntArrayField - Convert list like `1,2,3,4,5` into python list(consists of python's `int` object)
+ utils
+ json2form - convert python dict into `MultiDict` which can be read by wtforms.

##web_utils.json_forms
Validate json string or dict object in wtforms's way.
Just inherit `JsonForm` class and call `validate` method to do validation.
Validation by `JsonSchema` , [Validation Quick Start](http://json-schema.org/latest/json-schema-validation.html).
Example listed below:
```python
class NewPMSSchema(JsonForm):
schema = {
"type": "object",
"properties": {
"to_uid": {
"type": "number",
},
"content": {
"type": "string",
},
"test": {
"type": "object",
"properties": {
"test1": {
"type": "integer",
}
}
},
},
"required": ['to_uid', 'content'],
}

form = NewPMSSchema({'to_uid': 'a', 'content': 1})
# result
result = form.validate()
# errors
if not result:
print form.errors
```

##web_utils.security
Not recommend to use it.

##web_utils._sqlalchemy
A sqlalchemy model to json data converter with white list and custom converter support.

###DBFCMixin
Just inherit it in your sqlalchemy model and call `as_dict` method to output python dict.
`class._default_output` is required.
Example listed below:

```python
class APIStorage(Base, DBFCMixin, StorageBackendMixin):

__tablename__ = "api_storage"
# white list
_default_output = ('id', 'category', 'resource_name', 'document')

id = Column(Integer, primary_key=True, autoincrement=True)
category = Column(Text, nullable=False)
resource_name = Column(Text, nullable=False)
body = Column(Text, nullable=False)
ctime = Column(DateTime, default=datetime.datetime.utcnow)

# call as_dict method
model_instance = dbsession.query(APIStorage).first()
model_instance.as_dict(pure=False) #False is default , with white list support.

```

###DBFieldConverter
Low level API for DBFCMixin
Quick example:

```python
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class APIStorage(Base):

__tablename__ = "api_storage"
_default_output = ('id', 'category', 'resource_name', 'document')

id = Column(Integer, primary_key=True, autoincrement=True)
category = Column(Text, nullable=False)
resource_name = Column(Text, nullable=False)
body = Column(Text, nullable=False)
ctime = Column(DateTime, default=datetime.datetime.utcnow)

# convert and output

model_instance = dbsession.query(APIStorage).first()

converter = DBFC(model_instance, model_instance._default_output)

converter.as_dict()

# as list
converter.as_list()

# without white list(output all data field)
converter.as_dict(pure=True)
```

####Register a Converter
DBFieldConverter supports Converter by sqlalchemy's field type.
```python
from sqlalchemy import Text
DBFieldConverter.register(Text)
```
will register Text type in DBFC.
Note: without registered, DBFieldConverter will print `warning` information in console.

```python
DBFieldConverter.register(Text, lambda x:x[-1])
```
will output the last char of the input field which type is `Text`.

You can also pass `registry` to DBFieldConverter `__init__` method to specify `field type converter`.
For example:
```python
from sqlalchemy import Text
converter = DBFC(model_instance, model_instance._default_output, registry={Text: lambda x: x[-1]})
```
**Note:** This registry will not affect other instance's registry of DBFieldConverter since it's `instance registry`.
Otherwise, `DBFC.register` register class converter in it's registry, every instance will be affected.

###form2model
Easy set `wtfomrs` `Form` data to sqlalchemy's model field, name by name.

```python
form2model(form, model_instance, exclude=None)
```


##web_utils.extra
Some utils about argument parse ,datetime format.
+ GetSingleArgument
+ bool(cls, value, default=False) default value support, will not return None.
+ integer(cls, value, default, nmin=None, nmax=None) - parse integer from string, return default value if not in given range.
+ string(cls, value, default='') - default value support
+ format_timestamp
from tornado core, to format timestamp
```python
>>> format_timestamp(1359312200)
'Sun, 27 Jan 2013 18:43:20 GMT'
```
+ AttrDict
Simple wrapper for `attr dict`
```
d = AttrDict({'a': 1})
d.a # output 1
```
Many problem when use it, pay attention before you really know what you are doing.



2015-03-19 fix bug in `JsonForm` and add integer and string auto-converter in `JsonForm`
2015-02-13 update readme.