[tor-commits] [stem/master] Describe descriptor creation in our tutorials

[atagar at torproject.org]

commit 5caf80b2bd39964599ce70b5acca9e224c0f3b93
Author: Damian Johnson <atagar at torproject.org>
Date:   Tue May 2 12:50:14 2017 -0700

    Describe descriptor creation in our tutorials
    
    Noting our new capability in our tutorials with a couple examples.
---
 docs/_static/example/create_descriptor.py         |  9 +++++
 docs/_static/example/create_descriptor_content.py |  3 ++
 docs/change_log.rst                               |  1 +
 docs/tutorials/mirror_mirror_on_the_wall.rst      | 40 +++++++++++++++++++++++
 4 files changed, 53 insertions(+)

diff --git a/docs/_static/example/create_descriptor.py b/docs/_static/example/create_descriptor.py
new file mode 100644
index 0000000..29c5654
--- /dev/null
+++ b/docs/_static/example/create_descriptor.py
@@ -0,0 +1,9 @@
+from stem.descriptor.server_descriptor import RelayDescriptor
+
+# prints 'caerSidi (71.35.133.197:9001)'
+desc = RelayDescriptor.create()
+print("%s (%s:%s)" % (desc.nickname, desc.address, desc.or_port))
+
+# prints 'demo (127.0.0.1:80)'
+desc = RelayDescriptor.create({'router': 'demo 127.0.0.1 80 0 0'})
+print("%s (%s:%s)" % (desc.nickname, desc.address, desc.or_port))
diff --git a/docs/_static/example/create_descriptor_content.py b/docs/_static/example/create_descriptor_content.py
new file mode 100644
index 0000000..e4a9f2b
--- /dev/null
+++ b/docs/_static/example/create_descriptor_content.py
@@ -0,0 +1,3 @@
+from stem.descriptor.server_descriptor import RelayDescriptor
+
+print(RelayDescriptor.content({'router': 'demo 127.0.0.1 80 0 0'}))
diff --git a/docs/change_log.rst b/docs/change_log.rst
index f8985f9..b99d0b4 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -53,6 +53,7 @@ The following are only available within Stem's `git repository
 
  * **Descriptors**
 
+  * Supporting `descriptor creation <tutorials/mirror_mirror_on_the_wall.html#can-i-create-descriptors>`_ (:trac:`10227`)
   * Support and validation for `ed25519 certificates <api/descriptor/certificate.html>`_ (`spec <https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt>`_, :trac:`21558`)
   * Moved from the deprecated `pycrypto <https://www.dlitz.net/software/pycrypto/>`_ module to `cryptography <https://pypi.python.org/pypi/cryptography>`_ for validating signatures (:trac:`21086`)
   * Sped descriptor reading by ~25% by deferring defaulting when validating
diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst
index 9d018fc..d9ba6e0 100644
--- a/docs/tutorials/mirror_mirror_on_the_wall.rst
+++ b/docs/tutorials/mirror_mirror_on_the_wall.rst
@@ -9,6 +9,7 @@ with what they are and where to get them then you may want to skip to the end.
 * :ref:`where-can-i-get-the-current-descriptors`
 * :ref:`where-can-i-get-past-descriptors`
 * :ref:`can-i-get-descriptors-from-the-tor-process`
+* :ref:`can-i-create-descriptors`
 * :ref:`validating-the-descriptors-content`
 * :ref:`saving-and-loading-descriptors`
 * :ref:`putting-it-together`
@@ -164,6 +165,45 @@ through Tor's control socket...
 
 .. _validating-the-descriptors-content:
 
+.. _can-i-create-descriptors:
+
+Can I create descriptors?
+-------------------------
+
+Besides reading descriptors you can create them too. This is most commonly done
+for test data. To do so simply use the
+:func:`~stem.descriptor.__init__.Descriptor.create` method of
+:class:`~stem.descriptor.__init__.Descriptor` subclasses...
+
+.. literalinclude:: /_static/example/create_descriptor.py
+   :language: python
+
+Unspecified mandatory fields are filled with mock data. You can also use
+:func:`~stem.descriptor.__init__.Descriptor.content` to get a string
+descriptor...
+
+.. literalinclude:: /_static/example/create_descriptor_content.py
+   :language: python
+
+::
+
+  router demo 127.0.0.1 80 0 0
+  published 2012-03-01 17:15:27
+  bandwidth 153600 256000 104590
+  reject *:*
+  onion-key
+  -----BEGIN RSA PUBLIC KEY-----
+  MIGJAoGBAJv5IIWQ+WDWYUdyA/0L8qbIkEVH/cwryZWoIaPAzINfrw1WfNZGtBmg
+  skFtXhOHHqTRN4GPPrZsAIUOQGzQtGb66IQgT4tO/pj+P6QmSCCdTfhvGfgTCsC+
+  WPi4Fl2qryzTb3QO5r5x7T8OsG2IBUET1bLQzmtbC560SYR49IvVAgMBAAE=
+  -----END RSA PUBLIC KEY-----
+  signing-key
+  ...
+
+**Note:** Stem doesn't yet support signing its descriptors (:trac:`10227`).
+Until it does try using `leekspin <https://pypi.python.org/pypi/leekspin>`_
+instead.
+
 Validating the descriptor's content
 -----------------------------------