Permalink
Browse files

update doc of the new API

  • Loading branch information...
1 parent 0e9f4ce commit d2b59e80f86d4c50b6aa65317f72a334f62a813b namlook@nichjo committed Jan 7, 2010
Showing with 5,208 additions and 634 deletions.
  1. +0 −1 .hgignore
  2. +26 −93 README
  3. +3 −3 doc/conf.py
  4. +1 −4 doc/index.txt
  5. +1 −1 doc/inheritance.txt
  6. +66 −0 doc/internal_structure.txt
  7. +142 −0 doc/migration.txt
  8. BIN doc/mongokit_logo.odg
  9. +79 −0 doc/new_way.txt
  10. +89 −0 doc/old/doc_4.1/Makefile
  11. BIN doc/old/doc_4.1/_build/doctrees/cascade.doctree
  12. BIN doc/old/doc_4.1/_build/doctrees/environment.pickle
  13. BIN doc/old/doc_4.1/_build/doctrees/index.doctree
  14. BIN doc/old/doc_4.1/_build/doctrees/inheritance.doctree
  15. BIN doc/old/doc_4.1/_build/doctrees/internal_structure.doctree
  16. BIN doc/old/doc_4.1/_build/doctrees/introduction.doctree
  17. BIN doc/old/doc_4.1/_build/doctrees/mongodb_auth.doctree
  18. BIN doc/old/doc_4.1/_build/doctrees/pylons_support.doctree
  19. BIN doc/old/doc_4.1/_build/doctrees/reference/mongokit.document.doctree
  20. BIN doc/old/doc_4.1/_build/doctrees/reference/mongokit.mongo_exceptions.doctree
  21. BIN doc/old/doc_4.1/_build/doctrees/relations.doctree
  22. BIN doc/old/doc_4.1/_build/doctrees/tutorial.doctree
  23. +1 −0 doc/old/doc_4.1/_build/html
  24. +405 −0 doc/old/doc_4.1/_static/basic.css
  25. BIN doc/old/doc_4.1/_static/contents.png
  26. +232 −0 doc/old/doc_4.1/_static/doctools.js
  27. BIN doc/old/doc_4.1/_static/file.png
  28. +32 −0 doc/old/doc_4.1/_static/jquery.js
  29. BIN doc/old/doc_4.1/_static/minus.png
  30. BIN doc/old/doc_4.1/_static/navigation.png
  31. BIN doc/old/doc_4.1/_static/plus.png
  32. +61 −0 doc/old/doc_4.1/_static/pygments.css
  33. +467 −0 doc/old/doc_4.1/_static/searchtools.js
  34. +323 −0 doc/old/doc_4.1/_static/sphinxdoc.css
  35. +237 −0 doc/old/doc_4.1/_theme/agogo/layout.html
  36. +329 −0 doc/old/doc_4.1/_theme/agogo/static/agogo.css_t
  37. BIN doc/old/doc_4.1/_theme/agogo/static/bgfooter.png
  38. BIN doc/old/doc_4.1/_theme/agogo/static/bgtop.png
  39. +18 −0 doc/old/doc_4.1/_theme/agogo/theme.conf
  40. +221 −0 doc/old/doc_4.1/_theme/nature/static/nature.css_t
  41. +54 −0 doc/old/doc_4.1/_theme/nature/static/pygments.css
  42. +6 −0 doc/old/doc_4.1/_theme/nature/theme.conf
  43. 0 doc/{ → old/doc_4.1}/cascade.txt
  44. +196 −0 doc/old/doc_4.1/conf.py
  45. +24 −0 doc/old/doc_4.1/index.txt
  46. +39 −0 doc/old/doc_4.1/inheritance.txt
  47. +66 −0 doc/old/doc_4.1/internal_structure.txt
  48. +1 −0 doc/old/doc_4.1/introduction.txt
  49. 0 doc/{ → old/doc_4.1}/mongodb_auth.txt
  50. BIN doc/old/doc_4.1/mongokit_icon.png
  51. BIN doc/old/doc_4.1/mongokit_logo.odg
  52. BIN doc/old/doc_4.1/mongokit_logo.png
  53. +79 −0 doc/old/doc_4.1/new_way.txt
  54. 0 doc/{ → old/doc_4.1}/pylons_support.txt
  55. 0 doc/{ → old/doc_4.1}/relations.txt
  56. +930 −0 doc/old/doc_4.1/tutorial.txt
  57. +207 −224 doc/tutorial.txt
  58. +0 −9 mongokit/ext/__init__.py
  59. +0 −109 mongokit/ext/mongodb_auth.py
  60. +0 −177 mongokit/ext/pylons_env.py
  61. +1 −10 mongokit/{mongo_document.py → mongo_document.py.orig}
  62. +838 −0 mongokit/mongo_document.py_good
  63. +34 −3 tests/test_autoref.py
View
@@ -3,7 +3,6 @@ syntax: glob
.*.swp
.coverage
data
-old
Ekeet.egg-info
Masheet.egg-info
dist
View
119 README
@@ -21,24 +21,22 @@ Features
* default values
* custom validators
* inheritance and polymorphisme support
- * delete cascade support
* versionized document support (still in alpha stage)
* partial auth support (it brings a simple User model)
- * Pylons Web Framework integration support
- * Operator for validation (currently : OR, NOT and IS)
- * Mongodb auth support
- * full relation support
+ * operator for validation (currently : OR, NOT and IS)
+ * simple web framework integration
+ * import/export to json
A quick example
===============
-MongoDocument are enhanced python dictionnary with a ``validate()`` method.
-A MongoDocument declaration look like that::
+Document are enhanced python dictionnary with a ``validate()`` method.
+A Document declaration look like that::
- >>> from mongokit import MongoDocument
+ >>> from mongokit import *
>>> import datetime
- >>> class BlogPost(MongoDocument):
+ >>> class BlogPost(Document):
... db_name = 'test'
... collection_name = 'tutorial'
... structure = {
@@ -51,18 +49,24 @@ A MongoDocument declaration look like that::
... required_fields = ['title','author', 'date_creation']
... default_values = {'rank':0, 'date_creation':datetime.datetime.utcnow}
...
- >>> blogpost = BlogPost()
+
+We fire a connection and register our objects.
+
+ >>> con = Connection()
+ >>> con.register([BlogPost])
+ >>> blogpost = con.test.example.BlogPost() # this use the db "test" and the collection "example"
>>> blogpost['title'] = u'my title'
>>> blogpost['body'] = u'a body'
>>> blogpost['author'] = u'me'
- >>> blogpost.validate()
- >>> blogpost # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+ >>> blogpost
{'body': u'a body', 'title': u'my title', 'date_creation': datetime.datetime(...), 'rank': 0, 'author': u'me'}
>>> blogpost.save()
+Saving the object will call the `validate()` method.
+
And you can use more complex structure::
- >>> class ComplexDoc(MongoDocument):
+ >>> class ComplexDoc(Document):
... db_name = 'test'
... collection_name = 'tutorial'
... structure = {
@@ -86,20 +90,15 @@ on the freenode #mongodb irc channel or on twitter_.
Change Log
==========
-v.dev
------
- * add possibility to fetch raw data efficiently
- (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#getting-raw-data)
- * add connection sharing beetween documents
- (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#changing-collection-dynamically)
- * add connection size validation
- ()
- * fix issue with compound keys indexes. Some indexes description are deprecated.
- (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#indexes)
- * collection are now passed to the result objects when making a query.
- (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#query)
- * a pymongo's collection can now be pass to the constructor
- (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#changing-collection-dynamically)
+v0.5
+----
+ * refactoring API which is getting much much more cleaner. Please see the migration_ page to keep your code up to date
+ * 100% code coverage by 148 unit tests
+ * lot of bug fix (too many to list them here)
+ * add document size validation
+ * add cross database reference support
+
+.. _migration : http://bytebucket.org/namlook/mongokit/wiki/html/migration.html
v0.4
----
@@ -119,72 +118,6 @@ v0.4
(http://bytebucket.org/namlook/mongokit/wiki/html/relations.html)
* add long type support
-API change
-^^^^^^^^^^
-
-Adding more authorized_types
-++++++++++++++++++++++++++++
-
-`authorized_types` is not in the mongokit module anymore
-but has been integrated to the `MongoDocument` object.
-This allow to changed dynamically the authorized_types list at
-runtime.
-
-So, if you wan to add more types in authorized_types, you need to do:
-
->>> class MyDoc(MongoDocument):
-... structure = {
-... "foo":str,
-... }
-... authorized_types = MongoDocument.authorized_types + [str]
->>> mydoc = MyDoc()
->>> mydoc['foo'] = 'bla'
->>> mydoc.validate()
-
-New CustomType API
-++++++++++++++++++
-
-The `CustomType` api has little changed.
- * You must specify a `mongo_type` property in the `CustomType` class. this
- will describes the type of the value stored in the mongodb.
- * If you want more validation, you can specify a `python_type` property which is
- the python type the value will be converted. This is a good thing to specify it
- as it make a good documentation.
- * There is no `custom_types` descriptor anymore. The `CustomType` is set
- directly in the field. Plus, the `CustomType` must be instanciated.
-
-So, the new way of using `CustomType` look like this::
-
- >>> class CustomDate(CustomType):
- ... mongo_type = unicode
- ... python_type = datetime.datetime # optional, just for more validation
- ... def to_bson(self, value):
- ... """convert type to a mongodb type"""
- ... return unicode(datetime.datetime.strftime(value,'%y-%m-%d'))
- ... def to_python(self, value):
- ... """convert type to a python object"""
- ... if value is not None:
- ... return datetime.datetime.strptime(value, '%y-%m-%d')
-
- Now, let's create a MongoDocument:
-
- >>> class Foo(MongoDocument):
- ... db_name = 'test'
- ... collection_name = 'tutorial'
- ... structure = {
- ... 'foo':{
- ... 'date': CustomDate(),
- ... },
- ... }
- ... default_values = {'foo.date':u'08-06-07'}
-
-Autoreference
-+++++++++++++
-
-The internal structure of processing embeded document as changed and use the `CustomType` way.
-The advantage is that your data are not pollued by extra field anymore. So the '_ns' field is not
-added any more.
-
v0.3.3
------
View
@@ -38,16 +38,16 @@
# General information about the project.
project = u'MongoKit'
-copyright = u'2009, Namlook'
+copyright = u'2009-2010, Namlook'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '0.4'
+version = '0.5'
# The full version, including alpha/beta/rc tags.
-release = '0.4'
+release = '0.5'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
View
@@ -15,10 +15,7 @@ Contents:
introduction
tutorial
inheritance
- cascade
- relations
- pylons_support
- mongodb_auth
+ migration
View
@@ -6,7 +6,7 @@ And we want to build an object C from A and B. Let's build Root, A and B
first :
>>> from mongokit import *
->>> class Root(MongoDocument):
+>>> class Root(Document):
... structure = {
... "root":int,
... }
View
@@ -0,0 +1,66 @@
+Changing collection dynamically
+===============================
+
+Each `MongoDocument` must have a `db_host`, a `db_port`, a `db_name` and a `collection_name`.
+Those attributes are set when describing mongo documents. The connection, the db and the
+collection are then automatically created and attached to the object.
+
+But you might need to specify a different db or collection dynamically. For instance,
+say you want to store a User by database. You can't set the `db_name` and `collection_name`
+because it will change at each user.
+
+>>> class User(MongoDocument):
+... strucute = {'login':unicode, 'screen_name':unicode}
+... # we can set `db_name` here...
+
+Mongokit allow you to change those parameters on the fly. For this, you need to create
+another collection with the helper `get_collection`.
+
+>>> user_col = User.get_collection(db_name='namlook', collection_name='profile')
+
+Now, we can query the database by passing our new collection :
+
+>>> User.all({}, collection=col)
+
+You can pass those value to the `MongoDocument.__init__` :
+
+>>> user = User(db_name='namlook', collection_name='profile')
+>>> user['login'] = 'namlook'
+>>> user['screen_name'] = 'Namlook'
+
+calling `user.save()` will save the objet into the database 'namlook' in the collection 'profile'
+
+Internal structure
+==================
+
+SchemaDocument
+--------------
+
+A `SchemaDocument` brings all the structure and the validation layer. It is designed to be
+light and powerful with an simple api. This object is completely disconnected from the db and
+can be used stand-alone in another projects. Just copy the `schema_document.py` and the
+`operators.py` files. This object is pretty usefull if you wan to brings the validation layers
+of mongokit into another db. You'll need to implement all the database layer thought.
+
+MongoDocument
+-------------
+
+A `MongoDocument` brings all mongodb related staff to the SchemaDocument.
+This object defines all methods to deal with a mongod server.
+
+
+Little api changes
+==================
+
+There is a little api changes with this new changeset :
+
+ * `MongoDocument._connection` and `MongoDocument._collection` are removed and replaced by
+ public one : `MongoDocument.connection` and `MongoDocument.collection`.
+ * `MongoDocument.db` has appeared.
+ * `_get_connection()` was removed.
+ * `MongokitOperator` is now named to `SchemaOperator` for more consistency.
+ * `belong_to` becomes `belongs_to`
+
+Note that if you stiked to the tutorial and don't used internal methods or
+attributes, you don't need to change anything.
+
Oops, something went wrong.

0 comments on commit d2b59e8

Please sign in to comment.