[Checkins] SVN: zope.i18nmessageid/branches/tseaver-no_2to3/ Add Sphinx docs.
Tres Seaver
cvs-admin at zope.org
Fri Apr 6 22:49:03 UTC 2012
Log message for revision 125048:
Add Sphinx docs.
Changed:
A zope.i18nmessageid/branches/tseaver-no_2to3/docs/api.rst
U zope.i18nmessageid/branches/tseaver-no_2to3/docs/index.rst
A zope.i18nmessageid/branches/tseaver-no_2to3/docs/narr.rst
D zope.i18nmessageid/branches/tseaver-no_2to3/src/zope/i18nmessageid/messages.txt
-=-
Added: zope.i18nmessageid/branches/tseaver-no_2to3/docs/api.rst
===================================================================
--- zope.i18nmessageid/branches/tseaver-no_2to3/docs/api.rst (rev 0)
+++ zope.i18nmessageid/branches/tseaver-no_2to3/docs/api.rst 2012-04-06 22:48:59 UTC (rev 125048)
@@ -0,0 +1,5 @@
+:mod:`zope.i18nmessageid` API Reference
+=======================================
+
+
+.. automodule:: zope.i18nmessageid.message
Modified: zope.i18nmessageid/branches/tseaver-no_2to3/docs/index.rst
===================================================================
--- zope.i18nmessageid/branches/tseaver-no_2to3/docs/index.rst 2012-04-06 22:48:56 UTC (rev 125047)
+++ zope.i18nmessageid/branches/tseaver-no_2to3/docs/index.rst 2012-04-06 22:48:59 UTC (rev 125048)
@@ -11,8 +11,11 @@
.. toctree::
:maxdepth: 2
+ narr
+ api
+
Indices and tables
==================
Copied: zope.i18nmessageid/branches/tseaver-no_2to3/docs/narr.rst (from rev 125047, zope.i18nmessageid/branches/tseaver-no_2to3/src/zope/i18nmessageid/messages.txt)
===================================================================
--- zope.i18nmessageid/branches/tseaver-no_2to3/docs/narr.rst (rev 0)
+++ zope.i18nmessageid/branches/tseaver-no_2to3/docs/narr.rst 2012-04-06 22:48:59 UTC (rev 125048)
@@ -0,0 +1,164 @@
+Using :mod:`zope.i18nmessageid`
+===============================
+
+Rationale
+---------
+
+To translate any text, we must be able to discover the source domain
+of the text. A source domain is an identifier that identifies a
+project that produces program source strings. Source strings occur as
+literals in python programs, text in templates, and some text in XML
+data. The project implies a source language and an application
+context.
+
+Messages and Domains
+--------------------
+
+We can think of a source domain as a collection of messages and
+associated translation strings. The domain helps to disambiguate messages
+based on context: for instance, the message whose source string is "draw"
+means one thing in a first-person shooter game, and quite another in a
+graphics package: in the first case, the domain for the message might
+be "doom", while in the second it might be "gimp".
+
+We often need to create unicode strings that will be displayed by
+separate views. The view cannot translate the string without knowing
+its source domain. A string or unicode literal carries no domain
+information, therefore we use messages. Messages are unicode strings
+which carry a translation source domain and possibly a default
+translation.
+
+Message Factories
+-----------------
+
+Messages are created by a message factory belonging to a given translation
+domain. Each message factory is created by instantiating a
+:class:`~zope.i18nmessageid.message.MessageFactory`, passing the domain
+corresponding to the project which manages the corrresponding translations.
+
+.. doctest::
+
+ >>> from zope.i18nmessageid import MessageFactory
+ >>> factory = MessageFactory('myproject')
+ >>> foo = factory('foo')
+ >>> foo.domain
+ 'myproject'
+
+The Zope project uses the "zope" domain for its messages. This package
+exports an already-created factory for that domain:
+
+.. doctest::
+
+ >>> from zope.i18nmessageid import ZopeMessageFactory as _z_
+ >>> foo = _z_('foo')
+ >>> foo.domain
+ 'zope'
+
+
+Example Usage
+-------------
+
+In this example, we create a message factory and assign it to _. By
+convention, we use _ as the name of our factory to be compatible with
+translatable string extraction tools such as xgettext. We then call _
+with a string that needs to be translatable:
+
+.. doctest::
+
+ >>> from zope.i18nmessageid import MessageFactory, Message
+ >>> _ = MessageFactory("futurama")
+ >>> robot = _(u"robot-message", u"${name} is a robot.")
+
+Messages at first seem like they are unicode strings:
+
+.. doctest::
+
+ >>> robot == u'robot-message'
+ True
+ >>> isinstance(robot, unicode)
+ True
+
+The additional domain, default and mapping information is available
+through attributes:
+
+.. doctest::
+
+ >>> robot.default == u'${name} is a robot.'
+ True
+ >>> robot.mapping
+ >>> robot.domain
+ 'futurama'
+
+The message's attributes are considered part of the immutable message
+object. They cannot be changed once the message id is created:
+
+.. doctest::
+
+ >>> robot.domain = "planetexpress"
+ Traceback (most recent call last):
+ ...
+ TypeError: readonly attribute
+
+ >>> robot.default = u"${name} is not a robot."
+ Traceback (most recent call last):
+ ...
+ TypeError: readonly attribute
+
+ >>> robot.mapping = {u'name': u'Bender'}
+ Traceback (most recent call last):
+ ...
+ TypeError: readonly attribute
+
+If you need to change their information, you'll have to make a new
+message id object:
+
+.. doctest::
+
+ >>> new_robot = Message(robot, mapping={u'name': u'Bender'})
+ >>> new_robot == u'robot-message'
+ True
+ >>> new_robot.domain
+ 'futurama'
+ >>> new_robot.default == u'${name} is a robot.'
+ True
+ >>> new_robot.mapping == {u'name': u'Bender'}
+ True
+
+Last but not least, messages are reduceable for pickling:
+
+.. doctest::
+
+ >>> callable, args = new_robot.__reduce__()
+ >>> callable is Message
+ True
+ >>> args == (u'robot-message',
+ ... 'futurama',
+ ... u'${name} is a robot.',
+ ... {u'name': u'Bender'})
+ True
+
+ >>> fembot = Message(u'fembot')
+ >>> callable, args = fembot.__reduce__()
+ >>> callable is Message
+ True
+ >>> args == (u'fembot', None, None, None)
+ True
+
+Pickling and unpickling works, which means we can store message IDs in
+a database:
+
+.. doctest::
+
+ >>> from pickle import dumps, loads
+ >>> pystate = dumps(new_robot)
+ >>> pickle_bot = loads(pystate)
+ >>> (pickle_bot,
+ ... pickle_bot.domain,
+ ... pickle_bot.default,
+ ... pickle_bot.mapping) == (u'robot-message',
+ ... 'futurama',
+ ... u'${name} is a robot.',
+ ... {u'name': u'Bender'})
+ True
+ >>> pickle_bot.__reduce__()[0] is Message
+ True
Deleted: zope.i18nmessageid/branches/tseaver-no_2to3/src/zope/i18nmessageid/messages.txt
===================================================================
--- zope.i18nmessageid/branches/tseaver-no_2to3/src/zope/i18nmessageid/messages.txt 2012-04-06 22:48:56 UTC (rev 125047)
+++ zope.i18nmessageid/branches/tseaver-no_2to3/src/zope/i18nmessageid/messages.txt 2012-04-06 22:48:59 UTC (rev 125048)
@@ -1,133 +0,0 @@
-=============
-I18n Messages
-=============
-
-Rationale
----------
-
-To translate any text, we must be able to discover the source domain
-of the text. A source domain is an identifier that identifies a
-project that produces program source strings. Source strings occur as
-literals in python programs, text in templates, and some text in XML
-data. The project implies a source language and an application
-context.
-
-We can think of a source domain as a collection of messages and
-associated translation strings.
-
-We often need to create unicode strings that will be displayed by
-separate views. The view cannot translate the string without knowing
-its source domain. A string or unicode literal carries no domain
-information, therefore we use messages. Messages are unicode strings
-which carry a translation source domain and possibly a default
-translation. They are created by a message factory. The message
-factory is created by calling ``MessageFactory`` with the source
-domain.
-
-ZopeMessageFactory
-------------------
-
- >>> from zope.i18nmessageid import ZopeMessageFactory as _z_
- >>> foo = _z_('foo')
- >>> foo.domain
- 'zope'
-
-
-
-Example
--------
-
-In this example, we create a message factory and assign it to _. By
-convention, we use _ as the name of our factory to be compatible with
-translatable string extraction tools such as xgettext. We then call _
-with a string that needs to be translatable:
-
- >>> from zope.i18nmessageid import MessageFactory, Message
- >>> _ = MessageFactory("futurama")
- >>> robot = _(u"robot-message", u"${name} is a robot.")
-
-Messages at first seem like they are unicode strings:
-
- >>> robot == u'robot-message'
- True
- >>> isinstance(robot, unicode)
- True
-
-The additional domain, default and mapping information is available
-through attributes:
-
- >>> robot.default == u'${name} is a robot.'
- True
- >>> robot.mapping
- >>> robot.domain
- 'futurama'
-
-The message's attributes are considered part of the immutable message
-object. They cannot be changed once the message id is created:
-
- >>> robot.domain = "planetexpress"
- Traceback (most recent call last):
- ...
- TypeError: readonly attribute
-
- >>> robot.default = u"${name} is not a robot."
- Traceback (most recent call last):
- ...
- TypeError: readonly attribute
-
- >>> robot.mapping = {u'name': u'Bender'}
- Traceback (most recent call last):
- ...
- TypeError: readonly attribute
-
-If you need to change their information, you'll have to make a new
-message id object:
-
- >>> new_robot = Message(robot, mapping={u'name': u'Bender'})
- >>> new_robot == u'robot-message'
- True
- >>> new_robot.domain
- 'futurama'
- >>> new_robot.default == u'${name} is a robot.'
- True
- >>> new_robot.mapping == {u'name': u'Bender'}
- True
-
-Last but not least, messages are reduceable for pickling:
-
- >>> callable, args = new_robot.__reduce__()
- >>> callable is Message
- True
- >>> args == (u'robot-message', 'futurama', u'${name} is a robot.', {u'name': u'Bender'})
- True
-
- >>> fembot = Message(u'fembot')
- >>> callable, args = fembot.__reduce__()
- >>> callable is Message
- True
- >>> args == (u'fembot', None, None, None)
- True
-
-Message IDs and backward compatability
---------------------------------------
-
-The change to immutability is not a simple refactoring that can be
-coped with backward compatible APIs--it is a change in semantics.
-Because immutability is one of those "you either have it or you don't"
-things (like pregnancy or death), we will not be able to support both
-in one implementation.
-
-The proposed solution for backward compatability is to support both
-implementations in parallel, deprecating the mutable one. A separate
-factory, ``MessageFactory``, instantiates immutable messages, while
-the deprecated old one continues to work like before.
-
-The roadmap to immutable-only message ids is proposed as follows:
-
- Zope 3.1: Immutable message ids are introduced. Security
- declarations for mutable message ids are provided to make the
- stripping of security proxies unnecessary.
-
- Zope 3.2: Mutable message ids are deprecated.
-
- Zope 3.3: Mutable message ids are removed.
More information about the checkins
mailing list