[Zope3-checkins] SVN: Zope3/branches/ZopeX3-3.0/src/zope/app/
Convert more text files to ReST.
Fred L. Drake, Jr.
fred at zope.com
Fri Jul 16 14:00:44 EDT 2004
Log message for revision 26584:
Convert more text files to ReST.
Changed:
U Zope3/branches/ZopeX3-3.0/src/zope/app/ftp/README.txt
U Zope3/branches/ZopeX3-3.0/src/zope/app/observable/README.txt
U Zope3/branches/ZopeX3-3.0/src/zope/app/pluggableauth/README.txt
U Zope3/branches/ZopeX3-3.0/src/zope/app/sqlscript/README.txt
-=-
Modified: Zope3/branches/ZopeX3-3.0/src/zope/app/ftp/README.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/ftp/README.txt 2004-07-16 17:28:32 UTC (rev 26583)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/ftp/README.txt 2004-07-16 18:00:43 UTC (rev 26584)
@@ -1,26 +1,26 @@
+=====================
+How FTP Works in Zope
+=====================
-Here are some notes about the way FTP actually works in zope.
+- The FTP server implementation is in `zope.server.ftp.server`. See
+ the README.txt file there.
- - The FTP server implementation is in zope.server.ftp.server. See
- the README.txt file there.
+ The publisher-based ftp server is in `zope.server.ftp.publisher`.
- The publisher-based ftp server is in zope.server.ftp.publisher.
+ The FTP server gets wired up with a request factory that creates
+ ftp requests with ftp publication objects.
- The FTP server gets wired up with a request factory that creates
- ftp requests with ftp publication objects.
+- The ftp request object is defined in `zope.publisher.ftp`.
- - The ftp request object is defined in zope.publisher.ftp.
+- The ftp publication object is defined in `zope.app.publication.ftp`.
- - The ftp publication object is defined in zope.app.publication.ftp.
+ The publication object gets views to handle ftp requests. It
+ looks up a separate view for each method defined in
+ `zope.publisher.interfaces.ftp.IFTPPublisher`.
- The publication object gets views to handle ftp requests. It
- looks up a separate view for each method defined in
- zope.publisher.interfaces.ftp.IFTPPublisher.
+ We provide a single class here that implements all of these methods.
- We provide a single class here that implements all of these
- methods.
+ The view, in turn, uses adapters for the `IReadFile`, `IWriteFile`,
+ `IReadDirectory`, `IWriteDirectory`, `IFileFactory`, and
+ `IDirectoryFactory`, defined in `zope.app.filerepresentation.interfaces`.
- The view, in turn, uses adapters for the IReadFile, IWriteFile,
- IReadDirectory, IWriteDirectory, IFileFactory, and
- IDirectoryFactory, defined in zope.app.filerepresentation.interfaces.
-
Modified: Zope3/branches/ZopeX3-3.0/src/zope/app/observable/README.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/observable/README.txt 2004-07-16 17:28:32 UTC (rev 26583)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/observable/README.txt 2004-07-16 18:00:43 UTC (rev 26584)
@@ -8,20 +8,13 @@
The package provides an event channel for dispatching events to the
appropriate instance as well as an adapter from IAnnotatable to
-IObservable. This is important because an object must support
-IAnnotatable (and therefore IAnnotations) in order to support
+`IObservable`. This is important because an object must support
+`IAnnotatable` (and therefore `IAnnotations`) in order to support
instance-based subscriptions.
Subscriptions for a particular instance are stored in the instance's
-annotations, in a key defined in zope.app.observable.observable.key
+annotations, in a key defined in `zope.app.observable.observable.key`
(currently 'zope.app.observable'). The annotation stored in the key
is actually an Observers object, which is a local registry that is not
aware of the global registry in any way. More information on the
Observers object is available in observers.txt.
-
-
-
-
-
-
-$Id$
Modified: Zope3/branches/ZopeX3-3.0/src/zope/app/pluggableauth/README.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/pluggableauth/README.txt 2004-07-16 17:28:32 UTC (rev 26583)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/pluggableauth/README.txt 2004-07-16 18:00:43 UTC (rev 26584)
@@ -1,8 +1,10 @@
-$Id$
+=================================
+New Authentication Service Design
+=================================
-The current implementation will be replaced. Following is design
+The current implementation will be replaced. The following is a design
I came up with together with Jim Fulton.
- -- itamar
+-- itamar
Note that this design is implemented (in some form) by the pluggable
auth service. This document needs to be updated to reflect the final
@@ -10,49 +12,56 @@
Design notes for new AuthenticationService
-==========================================
+------------------------------------------
The service contains a list of user sources. They implement interfaces,
-starting with:
+starting with::
class IUserPassUserSource:
"""Authenticate using username and password."""
+
def authenticate(username, password):
"Returns boolean saying if such username/password pair exists"
class IDigestSupportingUserSource(IUserPassUserSource):
"""Allow fetching password, which is required by digest auth methods"""
+
def getPassword(username):
"Return password for username"
-etc.. Probably there will be others as well, for dealing with certificate
-authentication and what not. Probably we need to expand above interfaces
+etc. Probably there will be others as well, for dealing with certificate
+authentication and what not. Probably we need to expand above interfaces
to deal with principal titles and descriptions, and so on.
-A login method - cookie auth, HTTP basic auth, digest auth, FTP auth,
+A login method (cookie auth, HTTP basic auth, digest auth, FTP auth),
is registered as a view on one of the above interfaces.
+::
class ILoginMethodView:
+
def authenticate():
"""Return principal for request, or None."""
+
def unauthorized():
"""Tell request that a login is required."""
-The authentication service is then implemented something like this:
+The authentication service is then implemented something like this::
- class AuthenticationService:
- def authenticate(self, request):
- for us in self.userSources:
- loginView = getView(self, us, "login", request)
- principal = loginView.authenticate()
- if principal is not None:
- return principal
- def unauthorized(self, request):
- loginView = getView(self, self.userSources[0], request)
- loginView.unauthorized()
+ class AuthenticationService:
+
+ def authenticate(self, request):
+ for us in self.userSources:
+ loginView = getView(self, us, "login", request)
+ principal = loginView.authenticate()
+ if principal is not None:
+ return principal
+
+ def unauthorized(self, request):
+ loginView = getView(self, self.userSources[0], request)
+ loginView.unauthorized()
Modified: Zope3/branches/ZopeX3-3.0/src/zope/app/sqlscript/README.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/sqlscript/README.txt 2004-07-16 17:28:32 UTC (rev 26583)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/sqlscript/README.txt 2004-07-16 18:00:43 UTC (rev 26584)
@@ -1,131 +1,137 @@
+=======================================
Using additional DTML tags in SQLScript
+=======================================
- Inserting optional tests with 'sqlgroup'
+Inserting optional tests with 'sqlgroup'
+----------------------------------------
- It is sometimes useful to make inputs to an SQL statement
- optinal. Doing so can be difficult, because not only must the
- test be inserted conditionally, but SQL boolean operators may or
- may not need to be inserted depending on whether other, possibly
- optional, comparisons have been done. The 'sqlgroup' tag
- automates the conditional insertion of boolean operators.
+It is sometimes useful to make inputs to an SQL statement optinal.
+Doing so can be difficult, because not only must the test be inserted
+conditionally, but SQL boolean operators may or may not need to be
+inserted depending on whether other, possibly optional, comparisons
+have been done. The 'sqlgroup' tag automates the conditional
+insertion of boolean operators.
- The 'sqlgroup' tag is a block tag that has no attributes. It can
- have any number of 'and' and 'or' continuation tags.
+The 'sqlgroup' tag is a block tag that has no attributes. It can have
+any number of 'and' and 'or' continuation tags.
- Suppose we want to find all people with a given first or nick name
- and optionally constrain the search by city and minimum and
- maximum age. Suppose we want all inputs to be optional. We can
- use DTML source like the following::
+Suppose we want to find all people with a given first or nick name and
+optionally constrain the search by city and minimum and maximum age.
+Suppose we want all inputs to be optional. We can use DTML source
+like the following::
- <dtml-sqlgroup>
- <dtml-sqlgroup>
- <dtml-sqltest name column=nick_name type=nb multiple optional>
- <dtml-or>
- <dtml-sqltest name column=first_name type=nb multiple optional>
- </dtml-sqlgroup>
- <dtml-and>
- <dtml-sqltest home_town type=nb optional>
- <dtml-and>
- <dtml-if minimum_age>
- age >= <dtml-sqlvar minimum_age type=int>
- </dtml-if>
- <dtml-and>
- <dtml-if maximum_age>
- age <= <dtml-sqlvar maximum_age type=int>
- </dtml-if>
- </dtml-sqlgroup>
+ <dtml-sqlgroup>
+ <dtml-sqlgroup>
+ <dtml-sqltest name column=nick_name type=nb multiple optional>
+ <dtml-or>
+ <dtml-sqltest name column=first_name type=nb multiple optional>
+ </dtml-sqlgroup>
+ <dtml-and>
+ <dtml-sqltest home_town type=nb optional>
+ <dtml-and>
+ <dtml-if minimum_age>
+ age >= <dtml-sqlvar minimum_age type=int>
+ </dtml-if>
+ <dtml-and>
+ <dtml-if maximum_age>
+ age <= <dtml-sqlvar maximum_age type=int>
+ </dtml-if>
+ </dtml-sqlgroup>
- This example illustrates how groups can be nested to control
- boolean evaluation order. It also illustrates that the grouping
- facility can also be used with other DTML tags like 'if' tags.
+This example illustrates how groups can be nested to control boolean
+evaluation order. It also illustrates that the grouping facility can
+also be used with other DTML tags like 'if' tags.
- The 'sqlgroup' tag checks to see if text to be inserted contains
- other than whitespace characters. If it does, then it is inserted
- with the appropriate boolean operator, as indicated by use of an
- 'and' or 'or' tag, otherwise, no text is inserted.
+The 'sqlgroup' tag checks to see if text to be inserted contains other
+than whitespace characters. If it does, then it is inserted with the
+appropriate boolean operator, as indicated by use of an 'and' or 'or'
+tag, otherwise, no text is inserted.
- Inserting optional tests with 'sqlgroup'
+Inserting optional tests with 'sqlgroup'
+----------------------------------------
- It is sometimes useful to make inputs to an SQL statement
- optinal. Doing so can be difficult, because not only must the
- test be inserted conditionally, but SQL boolean operators may or
- may not need to be inserted depending on whether other, possibly
- optional, comparisons have been done. The 'sqlgroup' tag
- automates the conditional insertion of boolean operators.
+It is sometimes useful to make inputs to an SQL statement optinal.
+Doing so can be difficult, because not only must the test be inserted
+conditionally, but SQL boolean operators may or may not need to be
+inserted depending on whether other, possibly optional, comparisons
+have been done. The 'sqlgroup' tag automates the conditional
+insertion of boolean operators.
- The 'sqlgroup' tag is a block tag. It can
- have any number of 'and' and 'or' continuation tags.
+The 'sqlgroup' tag is a block tag. It can have any number of 'and' and
+'or' continuation tags.
- The 'sqlgroup' tag has an optional attribure, 'required' to
- specify groups that must include at least one test. This is
- useful when you want to make sure that a query is qualified, but
- want to be very flexible about how it is qualified.
+The 'sqlgroup' tag has an optional attribure, 'required' to specify
+groups that must include at least one test. This is useful when you
+want to make sure that a query is qualified, but want to be very
+flexible about how it is qualified.
- Suppose we want to find people with a given first or nick name,
- city or minimum and maximum age. Suppose we want all inputs to be
- optional, but want to require *some* input. We can
- use DTML source like the following::
+Suppose we want to find people with a given first or nick name, city
+or minimum and maximum age. Suppose we want all inputs to be
+optional, but want to require *some* input. We can use DTML source
+like the following::
- <dtml-sqlgroup required>
- <dtml-sqlgroup>
- <dtml-sqltest name column=nick_name type=nb multiple optional>
- <dtml-or>
- <dtml-sqltest name column=first_name type=nb multiple optional>
- </dtml-sqlgroup>
- <dtml-and>
- <dtml-sqltest home_town type=nb optional>
- <dtml-and>
- <dtml-if minimum_age>
- age >= <dtml-sqlvar minimum_age type=int>
- </dtml-if>
- <dtml-and>
- <dtml-if maximum_age>
- age <= <dtml-sqlvar maximum_age type=int>
- </dtml-if>
- </dtml-sqlgroup>
+ <dtml-sqlgroup required>
+ <dtml-sqlgroup>
+ <dtml-sqltest name column=nick_name type=nb multiple optional>
+ <dtml-or>
+ <dtml-sqltest name column=first_name type=nb multiple optional>
+ </dtml-sqlgroup>
+ <dtml-and>
+ <dtml-sqltest home_town type=nb optional>
+ <dtml-and>
+ <dtml-if minimum_age>
+ age >= <dtml-sqlvar minimum_age type=int>
+ </dtml-if>
+ <dtml-and>
+ <dtml-if maximum_age>
+ age <= <dtml-sqlvar maximum_age type=int>
+ </dtml-if>
+ </dtml-sqlgroup>
- This example illustrates how groups can be nested to control
- boolean evaluation order. It also illustrates that the grouping
- facility can also be used with other DTML tags like 'if' tags.
+This example illustrates how groups can be nested to control boolean
+evaluation order. It also illustrates that the grouping facility can
+also be used with other DTML tags like 'if' tags.
- The 'sqlgroup' tag checks to see if text to be inserted contains
- other than whitespace characters. If it does, then it is inserted
- with the appropriate boolean operator, as indicated by use of an
- 'and' or 'or' tag, otherwise, no text is inserted.
+The 'sqlgroup' tag checks to see if text to be inserted contains other
+than whitespace characters. If it does, then it is inserted with the
+appropriate boolean operator, as indicated by use of an 'and' or 'or'
+tag, otherwise, no text is inserted.
- Inserting values with the 'sqlvar' tag
+Inserting values with the 'sqlvar' tag
+--------------------------------------
- The 'sqlvar' tag is used to type-safely insert values into SQL
- text. The 'sqlvar' tag is similar to the 'var' tag, except that
- it replaces text formatting parameters with SQL type information.
+The 'sqlvar' tag is used to type-safely insert values into SQL text.
+The 'sqlvar' tag is similar to the 'var' tag, except that it replaces
+text formatting parameters with SQL type information.
- The sqlvar tag has the following attributes:
+The sqlvar tag has the following attributes:
- name -- The name of the variable to insert. As with other
- DTML tags, the 'name=' prefix may be, and usually is,
- ommitted.
+`name`
+ The name of the variable to insert. As with other DTML tags, the
+ 'name=' prefix may be, and usually is, ommitted.
- type -- The data type of the value to be inserted. This
- attribute is required and may be one of 'string',
- 'int', 'float', or 'nb'. The 'nb' data type indicates a
- string that must have a length that is greater than 0.
+`type`
+ The data type of the value to be inserted. This attribute is
+ required and may be one of 'string', 'int', 'float', or 'nb'. The
+ 'nb' data type indicates a string that must have a length that is
+ greater than 0.
- optional -- A flag indicating that a value is optional. If a
- value is optional and is not provided (or is blank
- when a non-blank value is expected), then the string
- 'null' is inserted.
+`optional`
+ A flag indicating that a value is optional. If a value is optional
+ and is not provided (or is blank when a non-blank value is
+ expected), then the string 'null' is inserted.
- For example, given the tag::
+For example, given the tag::
- <dtml-sqlvar x type=nb optional>
+ <dtml-sqlvar x type=nb optional>
- if the value of 'x' is::
+if the value of 'x' is::
- Let\'s do it
+ Let\'s do it
- then the text inserted is:
+then the text inserted is:
- 'Let''s do it'
+ 'Let''s do it'
- however, if x is ommitted or an empty string, then the value
- inserted is 'null'.
+however, if x is ommitted or an empty string, then the value inserted
+is 'null'.
More information about the Zope3-Checkins
mailing list