Traits, basic documents, utility fields. (#26)

Traits added:

* Collection
* Derived
* Expires
* Identified
* Localized
* Published
* Queryable

Major unrelated additions:

* String stripping and case conversion.  Fixes #33.
* Markdown field. Fixes #34.
* Path field. Fixes #35.

Minor additions and changes:

* Utility function: `utcnow`
* Improved docstring coverage and referential integrity.  Work on #16.
* Generalized programmers' representations.
* Improved minifying plugin name lookup for `PluginReference` fields.
* Correct regression in the ability to manipulate field attributes via class attribute access.
* Collation support.
* Various project metadata updates including pre-commit and testing:
   * Updated CPython, Pypy, and MongoDB versions on Travis.
   * Skip slow (and unreliable) capped collection tests on Pypy.
   * Step debugger integration.
* Adjustments to query fragment merging.
* Switch test logging capture plugin to eliminate warnings.
* Simplification for HasKinds field types to only support a single referenced kind.
* Corrected Reference field behaviours.
* Parametric adjustments for extended `push` options.
* Dead code removal.
* Updated example for latest usage patterns.
* Array and Embed default value handling to reduce boilerplate lambdas, tests, trait updates.
* Utilize MutableMapping subclasses to work around an issue on Pypy.  Fixes #32, reference #31.

.pre-commit-config.yaml

@@ -1,30 +1,30 @@
-- repo: https://github.com/pre-commit/pre-commit-hooks.git
-  sha: c8a1c91c762b8e24fdc5a33455ec10662f523328
-  hooks:
-    - id: check-added-large-files
-    - id: check-ast
-    - id: check-byte-order-marker
-    - id: check-docstring-first
-    - id: check-merge-conflict
-    - id: check-symlinks
-    - id: debug-statements
-    - id: detect-private-key
-    - id: end-of-file-fixer
-    - id: check-json
-    - id: check-xml
-    - id: check-yaml
-- repo: https://github.com/Lucas-C/pre-commit-hooks-safety
-  sha: v1.0.9
-  hooks:
-    - id: python-safety-dependencies-check
-- repo: https://github.com/Lucas-C/pre-commit-hooks-bandit
-  sha: v1.0.1
-  hooks:
-    - id: python-bandit-vulnerability-check
-- repo: local
-  hooks:
-    - id: py.test
-      name: py.test
-      language: system
-      entry: sh -c py.test
-      files: ''
+-   repo: https://github.com/pre-commit/pre-commit-hooks.git
+    sha: 46251c9523506b68419aefdf5ff6ff2fbc4506a4
+    hooks:
+    -   id: check-added-large-files
+    -   id: check-ast
+    -   id: check-byte-order-marker
+    -   id: check-docstring-first
+    -   id: check-merge-conflict
+    -   id: check-symlinks
+    -   id: debug-statements
+    -   id: detect-private-key
+    -   id: end-of-file-fixer
+    -   id: check-json
+    -   id: check-xml
+    -   id: check-yaml
+-   repo: https://github.com/Lucas-C/pre-commit-hooks-safety
+    sha: v1.1.0
+    hooks:
+    -   id: python-safety-dependencies-check
+-   repo: https://github.com/Lucas-C/pre-commit-hooks-bandit
+    sha: v1.0.3
+    hooks:
+    -   id: python-bandit-vulnerability-check
+-   repo: local
+    hooks:
+    -   id: py.test
+        name: py.test
+        language: system
+        entry: sh -c py.test
+        files: ''

.travis.yml

@@ -2,15 +2,6 @@ language: python
 sudo: false
 cache: pip
 
-addons:
-  apt:
-    sources:
-      - mongodb-upstart
-      - mongodb-3.2-precise
-    packages:
-      - mongodb-org-server
-      - mongodb-org-shell
-
 branches:
   except:
       - /^[^/]+/.+$/
@@ -19,13 +10,20 @@ branches:
 
 python:
   - "2.7"
-  - "pypy"
+  - "pypy-5.4.1"
   - "3.3"
   - "3.4"
   - "3.5"
+  - "3.6"
+
+before_install:
+  - wget http://fastdl.mongodb.org/linux/mongodb-linux-x86_64-3.4.1.tgz -O /tmp/mongodb.tgz
+  - tar -xvf /tmp/mongodb.tgz
+  - mkdir /tmp/data
+  - ${PWD}/mongodb-linux-x86_64-3.4.1/bin/mongod --dbpath /tmp/data --bind_ip 127.0.0.1 --noauth &> /dev/null &
 
 install:
-  - travis_retry pip install --upgrade setuptools pip pytest pytest-cov codecov 'setuptools_scm>=1.9'
+  - travis_retry pip install --upgrade setuptools pip pytest pytest-cov codecov 'setuptools_scm>=1.9' cffi
   - pip install -e '.[development,logger]'
 
 script:

Makefile

@@ -17,7 +17,8 @@ veryclean: clean
 	rm -rvf *.egg-info .packaging
 
 test: develop
-	./setup.py test
+	@clear
+	@pytest
 
 release:
 	./setup.py register sdist bdist_wheel upload ${RELEASE_OPTIONS}

example/readme.py

@@ -1,35 +1,56 @@
 # encoding: utf-8
 
+# Imports.
+
 from pymongo import MongoClient
 
-from marrow.mongo import Document, Index
+from marrow.mongo import Index
 from marrow.mongo.field import Array, Number, ObjectId, String
+from marrow.mongo.trait import Queryable
+
+
+# Connect to the test database on the local machine.
+
+db = MongoClient().test
 
-collection = MongoClient().test.collection
-collection.drop()
 
+# Define an Account object model and associated metadata.
 
-class Account(Document):
+class Account(Queryable):
+	__collection__ = 'collection'
+
 	username = String(required=True)
 	name = String()
 	locale = String(default='en-CA-u-tz-cator-cu-CAD', assign=True)
 	age = Number()
 
-	id = ObjectId('_id', assign=True)
-	tag = Array(String(), default=lambda: [], assign=True)
+	tag = Array(String(), assign=True)
 
 	_username = Index('username', unique=True)
 
 
+# Bind it to a database, then (re-)create the collection including indexes.
+
+collection = Account.bind(db).create_collection(drop=True)
+
+
+# Create a new record; this record is unsaved...
+
 alice = Account('amcgregor', "Alice Bevan-McGregor", age=27)
-print(alice.id)  # Already has an ID.
-print(alice.id.generation_time)  # This even includes the creation time.
 
-Account._username.create_index(collection)
+print(alice.id)  # It already has an ID, however!
+print(alice.id.generation_time)  # This includes the creation time.
+
+
+# Inserting it will add it to the storage back-end; the MongoDB database.
+
+result = alice.insert_one()
+
+assert result.acknowledged and result.inserted_id == alice
+
+
+# Now you can query Account objects for one with an appropriate username.
 
-result = collection.insert_one(alice)
-assert result.acknowledged and result.inserted_id == alice.id
+record = Account.find_one(username='amcgregor')
 
-record = collection.find_one(Account.username == 'amcgregor')
-record = Account.from_mongo(record)
-print(record.name)  # Alice Bevan-McGregor
+print(record.name)  # Alice Bevan-McGregor; it's already an Account instance.

marrow/mongo/__init__.py

@@ -7,10 +7,12 @@
 from .core import Document, Field, Index, __version__  # noqa
 from .query import Q, Ops, Filter, Update
 from .param import F, P, S, U
-from .util import Registry
+from .util import Registry, utcnow
 
 document = sys.modules['marrow.mongo.document'] = Registry('marrow.mongo.document')
 field = sys.modules['marrow.mongo.field'] = Registry('marrow.mongo.field')
+trait = sys.modules['marrow.mongo.trait'] = Registry('marrow.mongo.trait')
+
 
 __all__ = [
 	'Document',