{"action":"created","comment":{"url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/comments/77996671","id":77996671,"diff_hunk":"@@ -0,0 +1,219 @@\n+===========================\n+Installing and running ZODB\n+===========================\n+\n+This topic discusses some boring nitty-gritty details needed to\n+actually run ZODB.\n+\n+Installation\n+============\n+\n+Installation of ZODB is pretty straightforward using Python's\n+packaging system. For example, using pip::\n+\n+  pip install ZODB\n+\n+You may need additional optional packages, such as `ZEO\n+<https://pypi.python.org/pypi/ZEO>`_ or `RelStorage\n+<https://pypi.python.org/pypi/RelStorage>`_, depending your deployment\n+choices.\n+\n+Configuration\n+=============\n+\n+You can set up ZODB in your application using either Python, or\n+ZODB's configuration language.  For simple database setup, and\n+especially for exploration, the Python APIs are sufficient.\n+\n+For more complex configurations, you'll probably find ZODB's\n+configuration language easier to use.\n+\n+To understand database setup, it's important to understand ZODB's\n+architecture.  ZODB separates database functionality\n+from storage concerns. When you create a database object,\n+you specify a storage object for it to use, as in::\n+\n+    import ZODB, ZODB.FileStorage\n+\n+    storage = ZODB.FileStorage.FileStorage('mydata.fs')\n+    db = ZODB.DB(storage)\n+\n+So when you define a database, you'll also define a storage. In the\n+example above, we define a :class:`file storage\n+<ZODB.FileStorage.FileStorage.FileStorage>` and then use it to define\n+a database.\n+\n+Sometimes, storages are created through composition.  For example, if\n+we want to save space, we could layer a ``ZlibStorage``\n+[#zlibstoragefn]_ over the file storage::\n+\n+    import ZODB, ZODB.FileStorage, zc.zlibstorage\n+\n+    storage = ZODB.FileStorage.FileStorage('mydata.fs')\n+    compressed_storage = zc.zlibstorage.ZlibStorage(storage)\n+    db = ZODB.DB(compressed_storage)\n+\n+`ZlibStorage <https://pypi.python.org/pypi/zc.zlibstorage>`_\n+compresses database records using the compression algorithm used by\n+`gzip <http://www.gzip.org/>`_.\n+\n+Python configuration\n+--------------------\n+\n+To set up a database with Python, you'll construct a storage using the\n+:ref:`storage APIs <included-storages-label>`, and then pass the\n+storage to the :class:`~ZODB.DB` class to create a database, as shown\n+in the examples in the previous section.\n+\n+The :class:`~ZODB.DB` class also accepts a string path name as it's\n+storage argument to automatically create a file storage.  You can also\n+pass ``None`` as the storage to automatically use a\n+:class:`~ZODB.MappingStorage.MappingStorage`, which is convenient when\n+exploring ZODB::\n+\n+  db = ZODB.DB(None) # Create an in-memory database.\n+\n+Text configuration\n+------------------\n+\n+ZODB supports a text-based configuration language.  It uses a syntax\n+similar to Apache configuration files.  The syntax was chosen to be\n+familiar to site administrators.\n+\n+ZODB's text configuration uses `ZConfig\n+<https://pypi.python.org/pypi/ZConfig/3.1.0>`_. You can use ZConfig to\n+create your application's configuration, but it's more common to\n+include ZODB configuration strings in their own files or embedded in\n+simpler configuration files, such as `configarser\n+<https://docs.python.org/3/library/configparser.html#module-configparser>`_\n+files.\n+\n+A database configuration string has a ``zodb`` section wrapping a\n+storage section, as in::\n+\n+  <zodb>\n+    cache-size-bytes 100MB\n+    <mappingstorage>\n+    </mappingstorage>\n+  </zodb>\n+\n+.. -> snippet\n+\n+In the example above, the :ref:`mappingstorage\n+<mappingstorage-text-configuration>` section defines the storage used\n+by the database.\n+\n+To create a database from a string, use\n+:func:`ZODB.config.databaseFromString`::\n+\n+    >>> import ZODB.config\n+    >>> db = ZODB.config.databaseFromString(snippet)\n+\n+To load databases from file names or URLs, use\n+:func:`ZODB.config.databaseFromURL`.\n+\n+Using databases: connections\n+============================\n+\n+Once you have a database, you need to get a database connection to to\n+much of anything.  Connections take care of loading and saving objects\n+and manage object caches. Each connection has it's own cache\n+[#caches-are-expensive]_.\n+\n+Getting connections\n+-------------------\n+\n+Amongst [#amongst]_ the common ways of getting a connection:\n+\n+db.open()\n+   The database :meth:`~ZODB.DB.open` method opens a\n+   connection, returning a connection object::\n+\n+      >>> conn = db.open()\n+\n+   It's up to the application to call\n+   :meth:`~ZODB.Connection.Connection.close` when the application is\n+   done using the connection.\n+\n+   If changes are made, the application :ref:`commits transactions\n+   <commit-transactions>` to make them permanent.\n+\n+db.transaction() The database :meth:`~ZODB.DB.transaction` method\n+   returns a context manager that can be used with the `python with\n+   statement\n+   <https://docs.python.org/3/reference/compound_stmts.html#grammar-token-with_stmt>`_\n+   to execute a block of code in a transaction::\n+\n+     with db.transaction() as connection:\n+         connection.root.foo = 1\n+\n+   .. -> src\n+\n+      >>> exec(src)\n+      >>> with db.transaction() as connection:\n+      ...     print connection.root.foo\n+      1\n+\n+      >>> _ = conn.transaction_manager.begin() # get updates on conn\n+\n+   In the example above, we used ``as connection`` to get the database\n+   connection used in the variable ``connection``.\n+\n+some_object._p_jar\n+   For code that's already running in the context of an open\n+   connection, you can get the current connection as the ``_p_jar``\n+   attribute of some persistent object that was accessed via the\n+   connection.\n+\n+Getting objects\n+---------------\n+\n+Once you have a connection, you access objects by traversing the\n+object graph form the root object.","path":"documentation/guide/install-and-run.rst","position":172,"original_position":172,"commit_id":"86ed6e9dc69050e93232ebf5700a8088a64cf2cd","original_commit_id":"86ed6e9dc69050e93232ebf5700a8088a64cf2cd","user":{"login":"jamadden","id":1256082,"avatar_url":"https://avatars.githubusercontent.com/u/1256082?v=3","gravatar_id":"","url":"https://api.github.com/users/jamadden","html_url":"https://github.com/jamadden","followers_url":"https://api.github.com/users/jamadden/followers","following_url":"https://api.github.com/users/jamadden/following{/other_user}","gists_url":"https://api.github.com/users/jamadden/gists{/gist_id}","starred_url":"https://api.github.com/users/jamadden/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jamadden/subscriptions","organizations_url":"https://api.github.com/users/jamadden/orgs","repos_url":"https://api.github.com/users/jamadden/repos","events_url":"https://api.github.com/users/jamadden/events{/privacy}","received_events_url":"https://api.github.com/users/jamadden/received_events","type":"User","site_admin":false},"body":"form -> from","created_at":"2016-09-08T12:36:26Z","updated_at":"2016-09-08T12:36:26Z","html_url":"https://github.com/zopefoundation/zodbdocs/pull/24#discussion_r77996671","pull_request_url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24","_links":{"self":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/comments/77996671"},"html":{"href":"https://github.com/zopefoundation/zodbdocs/pull/24#discussion_r77996671"},"pull_request":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24"}}},"pull_request":{"url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24","id":84355880,"html_url":"https://github.com/zopefoundation/zodbdocs/pull/24","diff_url":"https://github.com/zopefoundation/zodbdocs/pull/24.diff","patch_url":"https://github.com/zopefoundation/zodbdocs/pull/24.patch","issue_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/24","number":24,"state":"open","locked":false,"title":"Setup and reference","user":{"login":"jimfulton","id":772727,"avatar_url":"https://avatars.githubusercontent.com/u/772727?v=3","gravatar_id":"","url":"https://api.github.com/users/jimfulton","html_url":"https://github.com/jimfulton","followers_url":"https://api.github.com/users/jimfulton/followers","following_url":"https://api.github.com/users/jimfulton/following{/other_user}","gists_url":"https://api.github.com/users/jimfulton/gists{/gist_id}","starred_url":"https://api.github.com/users/jimfulton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jimfulton/subscriptions","organizations_url":"https://api.github.com/users/jimfulton/orgs","repos_url":"https://api.github.com/users/jimfulton/repos","events_url":"https://api.github.com/users/jimfulton/events{/privacy}","received_events_url":"https://api.github.com/users/jimfulton/received_events","type":"User","site_admin":false},"body":"Added a topic on setting up databases for use in application. This led to adding reference docs.\r\n\r\nThis is a bit awkward to review because it depends on ZODB changes:\r\n\r\n  https://github.com/zopefoundation/ZODB/pull/101\r\n\r\nFor that reason, I've set up snapshot html site:\r\n\r\n  http://riversnake.com/daft-zodb/html/#learning-more\r\n\r\nIt might make more sense to move the docs into the zodb repository.  There will be a lot more cases where these docs and ZODB docstrings evolve together.\r\n\r\nFor that matter, combining these repos would make it possible to insist that user-visible changes include doc changes in the same PRs.","created_at":"2016-09-07T19:06:51Z","updated_at":"2016-09-08T12:36:26Z","closed_at":null,"merged_at":null,"merge_commit_sha":"bb240f35a21c3ce59b97322f298d7a9380389f51","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24/commits","review_comments_url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24/comments","review_comment_url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/24/comments","statuses_url":"https://api.github.com/repos/zopefoundation/zodbdocs/statuses/86ed6e9dc69050e93232ebf5700a8088a64cf2cd","head":{"label":"zopefoundation:setup-and-reference","ref":"setup-and-reference","sha":"86ed6e9dc69050e93232ebf5700a8088a64cf2cd","user":{"login":"zopefoundation","id":1163184,"avatar_url":"https://avatars.githubusercontent.com/u/1163184?v=3","gravatar_id":"","url":"https://api.github.com/users/zopefoundation","html_url":"https://github.com/zopefoundation","followers_url":"https://api.github.com/users/zopefoundation/followers","following_url":"https://api.github.com/users/zopefoundation/following{/other_user}","gists_url":"https://api.github.com/users/zopefoundation/gists{/gist_id}","starred_url":"https://api.github.com/users/zopefoundation/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zopefoundation/subscriptions","organizations_url":"https://api.github.com/users/zopefoundation/orgs","repos_url":"https://api.github.com/users/zopefoundation/repos","events_url":"https://api.github.com/users/zopefoundation/events{/privacy}","received_events_url":"https://api.github.com/users/zopefoundation/received_events","type":"Organization","site_admin":false},"repo":{"id":8858446,"name":"zodbdocs","full_name":"zopefoundation/zodbdocs","owner":{"login":"zopefoundation","id":1163184,"avatar_url":"https://avatars.githubusercontent.com/u/1163184?v=3","gravatar_id":"","url":"https://api.github.com/users/zopefoundation","html_url":"https://github.com/zopefoundation","followers_url":"https://api.github.com/users/zopefoundation/followers","following_url":"https://api.github.com/users/zopefoundation/following{/other_user}","gists_url":"https://api.github.com/users/zopefoundation/gists{/gist_id}","starred_url":"https://api.github.com/users/zopefoundation/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zopefoundation/subscriptions","organizations_url":"https://api.github.com/users/zopefoundation/orgs","repos_url":"https://api.github.com/users/zopefoundation/repos","events_url":"https://api.github.com/users/zopefoundation/events{/privacy}","received_events_url":"https://api.github.com/users/zopefoundation/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/zopefoundation/zodbdocs","description":"ZODB tutorial, articles, etc. (not the ZODB book)","fork":false,"url":"https://api.github.com/repos/zopefoundation/zodbdocs","forks_url":"https://api.github.com/repos/zopefoundation/zodbdocs/forks","keys_url":"https://api.github.com/repos/zopefoundation/zodbdocs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/zopefoundation/zodbdocs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/zopefoundation/zodbdocs/teams","hooks_url":"https://api.github.com/repos/zopefoundation/zodbdocs/hooks","issue_events_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/events{/number}","events_url":"https://api.github.com/repos/zopefoundation/zodbdocs/events","assignees_url":"https://api.github.com/repos/zopefoundation/zodbdocs/assignees{/user}","branches_url":"https://api.github.com/repos/zopefoundation/zodbdocs/branches{/branch}","tags_url":"https://api.github.com/repos/zopefoundation/zodbdocs/tags","blobs_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/refs{/sha}","trees_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/zopefoundation/zodbdocs/statuses/{sha}","languages_url":"https://api.github.com/repos/zopefoundation/zodbdocs/languages","stargazers_url":"https://api.github.com/repos/zopefoundation/zodbdocs/stargazers","contributors_url":"https://api.github.com/repos/zopefoundation/zodbdocs/contributors","subscribers_url":"https://api.github.com/repos/zopefoundation/zodbdocs/subscribers","subscription_url":"https://api.github.com/repos/zopefoundation/zodbdocs/subscription","commits_url":"https://api.github.com/repos/zopefoundation/zodbdocs/commits{/sha}","git_commits_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/commits{/sha}","comments_url":"https://api.github.com/repos/zopefoundation/zodbdocs/comments{/number}","issue_comment_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/comments{/number}","contents_url":"https://api.github.com/repos/zopefoundation/zodbdocs/contents/{+path}","compare_url":"https://api.github.com/repos/zopefoundation/zodbdocs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/zopefoundation/zodbdocs/merges","archive_url":"https://api.github.com/repos/zopefoundation/zodbdocs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/zopefoundation/zodbdocs/downloads","issues_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues{/number}","pulls_url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls{/number}","milestones_url":"https://api.github.com/repos/zopefoundation/zodbdocs/milestones{/number}","notifications_url":"https://api.github.com/repos/zopefoundation/zodbdocs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/zopefoundation/zodbdocs/labels{/name}","releases_url":"https://api.github.com/repos/zopefoundation/zodbdocs/releases{/id}","deployments_url":"https://api.github.com/repos/zopefoundation/zodbdocs/deployments","created_at":"2013-03-18T16:23:30Z","updated_at":"2016-06-17T12:54:02Z","pushed_at":"2016-09-07T19:06:52Z","git_url":"git://github.com/zopefoundation/zodbdocs.git","ssh_url":"git@github.com:zopefoundation/zodbdocs.git","clone_url":"https://github.com/zopefoundation/zodbdocs.git","svn_url":"https://github.com/zopefoundation/zodbdocs","homepage":null,"size":177,"stargazers_count":18,"watchers_count":18,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":9,"mirror_url":null,"open_issues_count":10,"forks":9,"open_issues":10,"watchers":18,"default_branch":"master"}},"base":{"label":"zopefoundation:new-guide","ref":"new-guide","sha":"73248f6810bb781980fd9e32c4805165c1e36152","user":{"login":"zopefoundation","id":1163184,"avatar_url":"https://avatars.githubusercontent.com/u/1163184?v=3","gravatar_id":"","url":"https://api.github.com/users/zopefoundation","html_url":"https://github.com/zopefoundation","followers_url":"https://api.github.com/users/zopefoundation/followers","following_url":"https://api.github.com/users/zopefoundation/following{/other_user}","gists_url":"https://api.github.com/users/zopefoundation/gists{/gist_id}","starred_url":"https://api.github.com/users/zopefoundation/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zopefoundation/subscriptions","organizations_url":"https://api.github.com/users/zopefoundation/orgs","repos_url":"https://api.github.com/users/zopefoundation/repos","events_url":"https://api.github.com/users/zopefoundation/events{/privacy}","received_events_url":"https://api.github.com/users/zopefoundation/received_events","type":"Organization","site_admin":false},"repo":{"id":8858446,"name":"zodbdocs","full_name":"zopefoundation/zodbdocs","owner":{"login":"zopefoundation","id":1163184,"avatar_url":"https://avatars.githubusercontent.com/u/1163184?v=3","gravatar_id":"","url":"https://api.github.com/users/zopefoundation","html_url":"https://github.com/zopefoundation","followers_url":"https://api.github.com/users/zopefoundation/followers","following_url":"https://api.github.com/users/zopefoundation/following{/other_user}","gists_url":"https://api.github.com/users/zopefoundation/gists{/gist_id}","starred_url":"https://api.github.com/users/zopefoundation/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zopefoundation/subscriptions","organizations_url":"https://api.github.com/users/zopefoundation/orgs","repos_url":"https://api.github.com/users/zopefoundation/repos","events_url":"https://api.github.com/users/zopefoundation/events{/privacy}","received_events_url":"https://api.github.com/users/zopefoundation/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/zopefoundation/zodbdocs","description":"ZODB tutorial, articles, etc. (not the ZODB book)","fork":false,"url":"https://api.github.com/repos/zopefoundation/zodbdocs","forks_url":"https://api.github.com/repos/zopefoundation/zodbdocs/forks","keys_url":"https://api.github.com/repos/zopefoundation/zodbdocs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/zopefoundation/zodbdocs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/zopefoundation/zodbdocs/teams","hooks_url":"https://api.github.com/repos/zopefoundation/zodbdocs/hooks","issue_events_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/events{/number}","events_url":"https://api.github.com/repos/zopefoundation/zodbdocs/events","assignees_url":"https://api.github.com/repos/zopefoundation/zodbdocs/assignees{/user}","branches_url":"https://api.github.com/repos/zopefoundation/zodbdocs/branches{/branch}","tags_url":"https://api.github.com/repos/zopefoundation/zodbdocs/tags","blobs_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/refs{/sha}","trees_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/zopefoundation/zodbdocs/statuses/{sha}","languages_url":"https://api.github.com/repos/zopefoundation/zodbdocs/languages","stargazers_url":"https://api.github.com/repos/zopefoundation/zodbdocs/stargazers","contributors_url":"https://api.github.com/repos/zopefoundation/zodbdocs/contributors","subscribers_url":"https://api.github.com/repos/zopefoundation/zodbdocs/subscribers","subscription_url":"https://api.github.com/repos/zopefoundation/zodbdocs/subscription","commits_url":"https://api.github.com/repos/zopefoundation/zodbdocs/commits{/sha}","git_commits_url":"https://api.github.com/repos/zopefoundation/zodbdocs/git/commits{/sha}","comments_url":"https://api.github.com/repos/zopefoundation/zodbdocs/comments{/number}","issue_comment_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/comments{/number}","contents_url":"https://api.github.com/repos/zopefoundation/zodbdocs/contents/{+path}","compare_url":"https://api.github.com/repos/zopefoundation/zodbdocs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/zopefoundation/zodbdocs/merges","archive_url":"https://api.github.com/repos/zopefoundation/zodbdocs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/zopefoundation/zodbdocs/downloads","issues_url":"https://api.github.com/repos/zopefoundation/zodbdocs/issues{/number}","pulls_url":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls{/number}","milestones_url":"https://api.github.com/repos/zopefoundation/zodbdocs/milestones{/number}","notifications_url":"https://api.github.com/repos/zopefoundation/zodbdocs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/zopefoundation/zodbdocs/labels{/name}","releases_url":"https://api.github.com/repos/zopefoundation/zodbdocs/releases{/id}","deployments_url":"https://api.github.com/repos/zopefoundation/zodbdocs/deployments","created_at":"2013-03-18T16:23:30Z","updated_at":"2016-06-17T12:54:02Z","pushed_at":"2016-09-07T19:06:52Z","git_url":"git://github.com/zopefoundation/zodbdocs.git","ssh_url":"git@github.com:zopefoundation/zodbdocs.git","clone_url":"https://github.com/zopefoundation/zodbdocs.git","svn_url":"https://github.com/zopefoundation/zodbdocs","homepage":null,"size":177,"stargazers_count":18,"watchers_count":18,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":9,"mirror_url":null,"open_issues_count":10,"forks":9,"open_issues":10,"watchers":18,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24"},"html":{"href":"https://github.com/zopefoundation/zodbdocs/pull/24"},"issue":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/24"},"comments":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/issues/24/comments"},"review_comments":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24/comments"},"review_comment":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/pulls/24/commits"},"statuses":{"href":"https://api.github.com/repos/zopefoundation/zodbdocs/statuses/86ed6e9dc69050e93232ebf5700a8088a64cf2cd"}}}}
{"actor":{"display_login":"jamadden"}}