[Checkins] SVN: z3c.authenticator/trunk/s - added doctests to long_description, so they'll show up on pypi homepage
Michael Howitz
mh at gocept.com
Sat Jan 3 08:25:55 EST 2009
Log message for revision 94471:
- added doctests to long_description, so they'll show up on pypi homepage
- made text a bit nicer to read
Changed:
U z3c.authenticator/trunk/setup.py
U z3c.authenticator/trunk/src/z3c/authenticator/README.txt
-=-
Modified: z3c.authenticator/trunk/setup.py
===================================================================
--- z3c.authenticator/trunk/setup.py 2009-01-03 12:25:27 UTC (rev 94470)
+++ z3c.authenticator/trunk/setup.py 2009-01-03 13:25:55 UTC (rev 94471)
@@ -29,7 +29,13 @@
description = "IAuthentication implementation for for Zope3",
long_description=(
read('README.txt')
+ + '\n\n.. contents::\n\n' +
+ read('src', 'z3c', 'authenticator', 'README.txt')
+ '\n\n' +
+ read('src', 'z3c', 'authenticator', 'group.txt')
+ + '\n\n' +
+ read('src', 'z3c', 'authenticator', 'vocabulary.txt')
+ + '\n\n' +
read('CHANGES.txt')
),
license = "ZPL 2.1",
Modified: z3c.authenticator/trunk/src/z3c/authenticator/README.txt
===================================================================
--- z3c.authenticator/trunk/src/z3c/authenticator/README.txt 2009-01-03 12:25:27 UTC (rev 94470)
+++ z3c.authenticator/trunk/src/z3c/authenticator/README.txt 2009-01-03 13:25:55 UTC (rev 94471)
@@ -2,8 +2,8 @@
IAuthentication Utility
=======================
-The Authenticator package provides a framework for authenticating principals
-and associating information with them. It uses plugins and subscribers to get
+The Authenticator package provides a framework for authenticating principals
+and associating information with them. It uses plugins and subscribers to get
its work done.
For a simple authentication utility to be used, it should be registered as a
@@ -17,7 +17,7 @@
Security
--------
-The Authenticator supports unique id tokens for principals. This means
+The Authenticator supports unique id tokens for principals. This means
principal that get deleted and again added with the same id, login etc. do
not have the same id again. We support this by generate a user id token
generated by the host id, timestamp, a random string and the login attribute.
@@ -26,11 +26,11 @@
What's different then in PluggableAuthentication
------------------------------------------------
-We use a different pattern for IAuthenticatorPlugins in this implementation
-then used in PluggableAuthentication located in zope.app.authentication.
-Because the pluggable authentication is not very handy when it comes to
-implement custom principal information. The IPrincipalInfo hook supporting
-not propagate the password of a IInternalPrincipal is droped in this
+We use a different pattern for IAuthenticatorPlugins in this implementation
+then used in PluggableAuthentication located in zope.app.authentication.
+Because the pluggable authentication is not very handy when it comes to
+implement custom principal information. The IPrincipalInfo hook supporting
+not propagate the password of a IInternalPrincipal is droped in this
implementation.
In our implementation we offer a IFoundPrincipal and IAuthenticatedPrincipal
@@ -38,12 +38,12 @@
it's context which is the real IUser.
The Authenticator doesn't use a prefix. The usage of a prefix is only
-implemented in the IGroupContainer.
+implemented in the IGroupContainer.
-We do not use a prefix in the IUserContainer because of the used unique user
-id tokens. This will make sure that the same principal id doesn't get used at
-a later time (common criteria). There is a ``add`` method which creates
-this id for you based on the login. The __setitem__ should not get used
+We do not use a prefix in the IUserContainer because of the used unique user
+id tokens. This will make sure that the same principal id doesn't get used at
+a later time (common criteria). There is a ``add`` method which creates
+this id for you based on the login. The __setitem__ should not get used
directly for adding IUser instances anymore. We heavily restricted the
usage of this method. See the inline doc tests in __setitem__ for more info.
@@ -51,7 +51,7 @@
Authentication
==============
-The primary job of Authenticator is to authenticate principals. It uses
+The primary job of Authenticator is to authenticate principals. It uses
two types of plug-ins in its work:
- Credentials Plugins
@@ -68,47 +68,55 @@
extracted by a credentials plugin. They are also typically able to create
principal objects for credentials they successfully authenticate.
-Given a request object, the Authenticator returns a principal object, if it
-can. The Authenticator utility does this by first iterateing through its
-credentials plugins to obtain a set of credentials. If it gets credentials, it
+Given a request object, the Authenticator returns a principal object, if it
+can. The Authenticator utility does this by first iterateing through its
+credentials plugins to obtain a set of credentials. If it gets credentials, it
iterates through its authenticator plugins to authenticate them.
-If an authenticator succeeds in authenticating a set of credentials, the
-Authenticator uses the authenticator to create a principal
-corresponding to the credentials. The authenticator notifies subscribers if
-an authenticated principal is created. Subscribers are responsible for adding
-data, especially groups, to the principal. Typically, if a subscriber adds
+If an authenticator succeeds in authenticating a set of credentials, the
+Authenticator uses the authenticator to create a principal
+corresponding to the credentials. The authenticator notifies subscribers if
+an authenticated principal is created. Subscribers are responsible for adding
+data, especially groups, to the principal. Typically, if a subscriber adds
data, it should also add corresponding interface declarations.
FAQ
---
-Here some usefull hints.
+Here some useful hints:
-How should I set permission for principals -- You can apply a roles to groups
- and apply permissions to roles. Or you can directly apply local permisssions
- to groups or to principals. After setup this mappings you can grant roles to
- groups. I always recommend a principal - group and permission - role mapping,
- then this gives you the most possible abstraction which is usefullif it comes
- to manage permission and principals without to invoke directly principals and
+How should I set permission for principals?
+
+ You can apply a roles to groups
+ and apply permissions to roles. Or you can directly apply local permisssions
+ to groups or to principals. After setup this mappings you can grant roles to
+ groups. I always recommend a principal - group and permission - role mapping,
+ then this gives you the most possible abstraction which is useful if it comes
+ to manage permission and principals without to invoke directly principals and
permissions itself. but of corse you can grant permissions to groups or the
- worst thing directly to principals. Grant permission to principals is only
- useful if it comes to selective local permission settings for selected
+ worst thing directly to principals. Grant permission to principals is only
+ useful if it comes to selective local permission settings for selected
principals e.g. a ownership like permission setup.
-How can I set permission for all principals -- You can register one
+How can I set permission for all principals?
+
+ You can register one
group as IEveryone utility. This IGroup utility get applied to all principals.
-Can I apply local groups to unauthenticated principals -- Yes this will work.
+Can I apply local groups to unauthenticated principals?
+
+ Yes this will work.
Since the last refactoring I refactored the IGroup implementation which makes
it compatible with the principalregistry API. This means you can now register
- one local group as a unnamed IUnauthenticatedGroup. You can also register one
- local group as an unnamed IAuthenticatedGroup utility which will get applied
- to every authenticated principal or a unnamed utility for
+ one local group as a unnamed IUnauthenticatedGroup. You can also register one
+ local group as an unnamed IAuthenticatedGroup utility which will get applied
+ to every authenticated principal or a unnamed utility for
IUnauthenticatedGroup.
-Can I apply a local group to every principal -- Yes, this is possible if
+Can I apply a local group to every principal?
+
+ Yes, this is possible if
register a local unnamed utility providing IEveryoneGroup.
@@ -148,13 +156,13 @@
>>> from z3c.authenticator.user import UserContainer
>>> authPlugin = UserContainer()
-
+
Now we have a UserContainer that provides a IUserContainer:
>>> interfaces.IUserContainer.providedBy(authPlugin)
True
-Now we will add the created principal to the principal container using the
+Now we will add the created principal to the principal container using the
containers method ``add``:
>>> uid, user = authPlugin.add(p)
@@ -162,9 +170,9 @@
The method returns the user id and the user object. The id get generated
by the host IP address, the time, a random string and the user login attr.
This token should be unique and guranted that it never get generated twice.
-This allows us to add, delete and add the same user again without that such a
+This allows us to add, delete and add the same user again without that such a
user will inherit existing permissions. We can test this token by compare it
-only with the __name__ of the object in this test since the token will
+only with the __name__ of the object in this test since the token will
different every testrun.
>>> user.__name__ == uid
@@ -190,15 +198,15 @@
let's register the UserContainer as a named IAuthenticatorPlugin utility:
>>> import zope.component
- >>> zope.component.provideUtility(authPlugin,
- ... provides=interfaces.IAuthenticatorPlugin,
+ >>> zope.component.provideUtility(authPlugin,
+ ... provides=interfaces.IAuthenticatorPlugin,
... name='My Authenticator Plugin')
-
+
Credentials Plugin
------------------
-After setup the user and user container, we'll create a simple credentials
+After setup the user and user container, we'll create a simple credentials
plugin:
>>> import zope.interface
@@ -209,7 +217,7 @@
... zope.interface.implements(interfaces.ICredentialsPlugin)
...
... def extractCredentials(self, request):
- ... return {'login':request.get('login', ''),
+ ... return {'login':request.get('login', ''),
... 'password':request.get('password', '')}
...
... def challenge(self, request):
@@ -223,22 +231,22 @@
Use the first and register the plugina utility:
>>> myCredentialsPlugin = MyCredentialsPlugin()
- >>> zope.component.provideUtility(myCredentialsPlugin,
+ >>> zope.component.provideUtility(myCredentialsPlugin,
... name='My Credentials Plugin')
AuthenticatedPrincipal and FoundPrincipal
-----------------------------------------
-While authenticator plugins provide user, they are not responsible for
+While authenticator plugins provide user, they are not responsible for
creating principals. This function is performed by the Authenticator:
>>> from z3c.authenticator.principal import AuthenticatedPrincipal
>>> from z3c.authenticator.principal import FoundPrincipal
- >>> zope.component.provideAdapter(AuthenticatedPrincipal,
+ >>> zope.component.provideAdapter(AuthenticatedPrincipal,
... provides=interfaces.IAuthenticatedPrincipal)
- >>> zope.component.provideAdapter(FoundPrincipal,
+ >>> zope.component.provideAdapter(FoundPrincipal,
... provides=interfaces.IFoundPrincipal)
@@ -288,7 +296,7 @@
Change login
------------
-Change the login of a principal is a allwas a critical task because such a
+Change the login of a principal is a allwas a critical task because such a
login together with a password is the key to our implemenation. Let's try to
change the login and check if everything is correct. We can do this by get the
principal from the UserContainer and change the login on the IUser
@@ -313,7 +321,7 @@
>>> auth.authenticate(request) == None
True
-The user bob has still the same id as bob2 since the user id token doesn't
+The user bob has still the same id as bob2 since the user id token doesn't
get changed be changing the login:
>>> bob.id == bob2.id
@@ -357,14 +365,14 @@
>>> event.principal.description
u''
-We provide subscribers to these events that can be used for doing custom
+We provide subscribers to these events that can be used for doing custom
processing. Note, the principal attibute provides a IAuthenticatedPrincipal:
>>> def addInfo(event):
... id = event.principal.id
... event.principal.description = 'Description for: %s' % id
- >>> zope.component.provideHandler(addInfo,
+ >>> zope.component.provideHandler(addInfo,
... [interfaces.IAuthenticatedPrincipalCreated])
Now, if we authenticate a principal, its description is set:
@@ -377,13 +385,13 @@
Customization
-------------
-Let's show you how the existing pattern can get used in a real use case. In
+Let's show you how the existing pattern can get used in a real use case. In
the next sample we like to provide a additional email attribute for principals.
First we have to define the interfaces declaring the email attribute:
>>> class IMyEmail(zope.interface.Interface):
... email = zope.schema.TextLine(
- ... title=u'EMail',
+ ... title=u'EMail',
... description=u'The EMail')
>>> class IMyUser(IMyEmail, interfaces.IUser):
@@ -392,17 +400,17 @@
>>> class IMyFoundPrincipal(IMyEmail, interfaces.IFoundPrincipal):
... """Custom IIMyFoundrincipal interface."""
- >>> class IMyAuthenticatedPrincipal(IMyEmail,
+ >>> class IMyAuthenticatedPrincipal(IMyEmail,
... interfaces.IAuthenticatedPrincipal):
... """Custom IAuthenticatedPrincipal interface."""
-After the schema, we define a custom principal implementation implementing
+After the schema, we define a custom principal implementation implementing
this interface:
>>> class MyUser(User):
... zope.interface.implements(IMyUser)
... def __init__(self, login, password, title, description, email):
- ... super(MyUser, self).__init__(login, password, title,
+ ... super(MyUser, self).__init__(login, password, title,
... description)
... self.email = email
@@ -423,16 +431,16 @@
... self.email = principal.email
Note that you can provide different attributes for the found and authenticated
-principal if needed. That's up to you what you like to do with this attributes
+principal if needed. That's up to you what you like to do with this attributes
later.
-Now we need to register our custom authenticated and found principal as
+Now we need to register our custom authenticated and found principal as
adapters:
- >>> zope.component.provideAdapter(MyAuthenticatedPrincipal,
+ >>> zope.component.provideAdapter(MyAuthenticatedPrincipal,
... provides=interfaces.IAuthenticatedPrincipal)
- >>> zope.component.provideAdapter(MyFoundPrincipal,
+ >>> zope.component.provideAdapter(MyFoundPrincipal,
... provides=interfaces.IFoundPrincipal)
Now we can use them without any other event subscriber or other registration
More information about the Checkins
mailing list