Pylons 2 users guide, first draft
Mike Orr
I've got a first draft of the Pylons 2 Users Guide done. The "hello
world" page is the only page that's completed; it goes through
installing a default application and looking through the application
code. I haven't gone through the Pylons code or BFG code or BFG manual
yet; I just went with "it must be so in order for the application code
to work", based on an earlier email exchange with Ben about the
application structure. The emails are also included for reference on a
separate page.
HTML version: http://sluggo.scrapping.cc/tmp/execution/
Repository: http://bitbucket.org/sluggo/execution
I found a few bugs and unknown things as I went along.
1) I couldn't create an application with a capital letter, as shown in
the traceback below.
2) The interactive traceback doesn't work; I just got an "Internal
Server Error" when I raised RuntimeError. This makes it impossible to
inspect a live request.
3) "paster shell" doesn't work, so I couldn't inspect a request that way.
4) Where is "routehelper" imported from?
5) What is Request.abort_session() for? is that to rollback changes to
the session? Or is it to forget the session when you log out?
6) Where is the code behind @action? The definition simply puts **kw
on the .__exposed__ attribute of the view method. But I couldn't find
anything in Pylons or BFG that would plug the return dict into a Mako
template and create a Response, yet it must be doing it somehow.
7) How do you change template engines? Specifically Genshi and Jinja2,
which are popular among Pylons users.
8) Is it worth documenting Request.add_response_callback(),
config.add_subscriber, .add_view, .add_route, and the config.__init__
args for Pylons? It seems like .add_handler is enough. I skipped over
a bunch of other Config methods that looked irrelevant.
* * *
With the "pylons_newminimal" template, I could make an application
called "hello" but not "Hello" (capitalized). When I created the
latter and tried to go to the home page, it said this. It's looking
for a module "Hello", even though the Python package is always
lowercase ("hello", aka "Hello/hello").
% paster serve development.ini
Starting server in PID 6486.
serving on 0.0.0.0:5000 view at http://127.0.0.1:5000
----------------------------------------
Exception happened during processing of request from ('127.0.0.1', 43651)
Traceback (most recent call last):
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/paste/httpserver.py",
line 1068, in process_request_in_thread
self.finish_request(request, client_address)
File "/usr/lib/python2.6/SocketServer.py", line 320, in finish_request
self.RequestHandlerClass(request, client_address, self)
File "/usr/lib/python2.6/SocketServer.py", line 615, in __init__
self.handle()
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/paste/httpserver.py",
line 442, in handle
BaseHTTPRequestHandler.handle(self)
File "/usr/lib/python2.6/BaseHTTPServer.py", line 329, in handle
self.handle_one_request()
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/paste/httpserver.py",
line 437, in handle_one_request
self.wsgi_execute()
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/paste/httpserver.py",
line 287, in wsgi_execute
self.wsgi_start_response)
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/router.py",
line 127, in __call__
response = view_callable(context, request)
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/configuration.py",
line 2310, in _bfg_class_requestonly_view
request=request)
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/renderers.py",
line 290, in render_to_response
result = self.render(value, system_values, request=request)
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/renderers.py",
line 269, in render
renderer = self.renderer
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/decorator.py",
line 17, in __get__
val = self.wrapped(inst)
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/renderers.py",
line 253, in renderer
return self.factory(self.renderer_name)
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/mako/__init__.py",
line 30, in renderer_factory
directories = [ abspath_from_resource_spec(d) for d in directories ]
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/repoze/bfg/mako/__init__.py",
line 79, in abspath_from_resource_spec
return pkg_resources.resource_filename(pname, filename)
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/distribute-0.6.10-py2.6.egg/pkg_resources.py",
line 862, in resource_filename
return get_provider(package_or_requirement).get_resource_filename(
File "/home/sluggo/exp/execution/workspace/venv/lib/python2.6/site-packages/distribute-0.6.10-py2.6.egg/pkg_resources.py",
line 180, in get_provider
__import__(moduleOrReq)
ImportError: No module named Hello
--
Mike Orr <slugg...@gmail.com>
Ben Bangert
> I've got a first draft of the Pylons 2 Users Guide done. The "hello
> world" page is the only page that's completed; it goes through
> installing a default application and looking through the application
> code. I haven't gone through the Pylons code or BFG code or BFG manual
> yet; I just went with "it must be so in order for the application code
> to work", based on an earlier email exchange with Ben about the
> application structure. The emails are also included for reference on a
> separate page.
Mike, this is a great first step! I think your "hello, world" in Pylons 2 should probably be adapted into a "Learning Pylons 2 for the Pylons 1 User" type document. As it does a great job explaining differences in terminology, where things come from (which is good for more advanced users, but maybe can be excluded for someone just wanting to know how to do things the new way), and some of the advantages of the new setup.
For the general documentation, here are the directions Chris and I were thinking would be a big priority:
- Integrated documentation
This means that *everything* one needs to write and use Pylons 2 will be in a single spot. This will involve documenting everything that we expect a user to use, in the main Pylons docs. All the configuration options and how sessions work (from Beaker), all the methods they would want to use of the Request and Response object (from Pylons, BFG, and WebOb), all the docs on how to register handlers, views, etc. (from BFG/Pylons), how to test an application and the methods/object docs, and probably all the important bits someone will use in Mako templates.
- Avoid mentioning what package provides what bit for the most part
This helps make the entire framework "feel" like an integrated whole. And the majority of the time, no user really cares that the Request/Response are WebOb subclasses, that the Pylons Configurator is a BFG subclass, that the events they imported from Pylons are shadow points for BFG ones, etc. Maybe in an Advanced chapter, where the components are dived into in detail, then the background of where these things originate will be mentioned. For the new and average user though, they just make the docs longer, and add unnecessary information that makes it feel more hacky. (I know that right now the main reason all the origins are mentioned is mainly because Pylons avoids re-documenting them, which will no longer be the case.)
- Document Imperative
Only the pure Python configuration style will be documented throughout the docs. Since we do want to have a single set of docs for *everything* and some use cases might have people reaching for ZCML, we'll also retain the ZCML configuration docs in a single chapter under an Advanced Pylons section. This also highlights Pylons focus on pure Python configuration.
The package list you note there has me thinking that maybe we can drop decorator, FormEncode, Routes, and WebHelpers from the Pylons dependencies. This means that the things using it in the Pylons code-base will need to be wrapped in try/except imports so that everything still works for legacy apps with Pylons 2.
Cheers,
Ben
Chris McDonough
Looks good, thanks a lot!
I added some comments via a fork at:
http://bitbucket.org/chrism/pylons-execution
I changed some paster template code as a result of your investigation;
the details are in the fork's comments.
- C
Chris McDonough
the ones I knew the answers to.
On Sun, 2010-09-12 at 04:24 -0700, Mike Orr wrote:
> I've got a first draft of the Pylons 2 Users Guide done. The "hello
> world" page is the only page that's completed; it goes through
> installing a default application and looking through the application
> code. I haven't gone through the Pylons code or BFG code or BFG manual
> yet; I just went with "it must be so in order for the application code
> to work", based on an earlier email exchange with Ben about the
> application structure. The emails are also included for reference on a
> separate page.
>
> HTML version: http://sluggo.scrapping.cc/tmp/execution/
>
> Repository: http://bitbucket.org/sluggo/execution
>
> I found a few bugs and unknown things as I went along.
>
> 1) I couldn't create an application with a capital letter, as shown in
> the traceback below.
>
> 2) The interactive traceback doesn't work; I just got an "Internal
> Server Error" when I raised RuntimeError. This makes it impossible to
> inspect a live request.
Both of these are fixed.
>
> 3) "paster shell" doesn't work, so I couldn't inspect a request that way.
This is not yet fixed.
> 4) Where is "routehelper" imported from?
>
> 5) What is Request.abort_session() for? is that to rollback changes to
> the session? Or is it to forget the session when you log out?
>
> 6) Where is the code behind @action? The definition simply puts **kw
> on the .__exposed__ attribute of the view method. But I couldn't find
> anything in Pylons or BFG that would plug the return dict into a Mako
> template and create a Response, yet it must be doing it somehow.
The @action decorator is more or less unrelated to the values returned
by a handler to a "renderer", except to name which renderer should be
used (e.g. renderer='sometemplate.mak'). (Most other arguments to the
@action decorator just make narrower the set of circumstances that will
cause the thing it's decorating to be found and executed).
See these sections of the BFG docs for information about what a
"renderer" does:
http://docs.repoze.org/bfg/1.3/narr/views.html#writing-view-callables-which-use-a-renderer
http://docs.repoze.org/bfg/1.3/narr/templates.html#templates-used-as-renderers-via-configuration
A templating system is just another kind of renderer, except you
register it for an extension (e.g. '.mak').
> 7) How do you change template engines? Specifically Genshi and Jinja2,
> which are popular among Pylons users.
You:
1) associate a "renderer" with a file extension (see comments in my fork
for a concrete mako example)
2) Then use a renderer= line in the @action configuration or use one of
these APIs to render such an extensioned template:
http://docs.repoze.org/bfg/1.3/api/renderers.html#repoze.bfg.renderers.render_to_response or http://docs.repoze.org/bfg/1.3/api/renderers.html#repoze.bfg.renderers.render
>
> 8) Is it worth documenting Request.add_response_callback(),
> config.add_subscriber, .add_view, .add_route, and the config.__init__
> args for Pylons? It seems like .add_handler is enough. I skipped over
> a bunch of other Config methods that looked irrelevant.
Probably not. All of this stuff is already well-documented in the BFG
docs, and it's likely we can just steal it from there if we think it's
necessary to include in the Pylons docs.
- C
Mike Orr
> MO: The static files are moved; they’re in the templates directory rather than in “hello/static”.
> CM: I think we'll want to move the static files out of the
templates directory and up into a peer of the templates directory.
I made a mistake here. The traditional Pylons location is
hello/public. not hello/static .So it's up to Ben whether to rename
the location. There are arguments both ways. "static" is a more
standard term, but "public" is backward compatible.
But why are they in hello/templates/static in the first place? Is that
what BFG normally does? It surprised me because they're not templates.
But I can vaguely see the logic if you consider "template" and
"renderer" in a broader sense than just template engines.
Ben, what do you want to do with static files? I'm assuming they're
staying where they are for now.
> MO: Routes-like traversal is built into BFG
> CM: "routes-like traversal" is probably not the right term.
"Routes-like pattern-based URL dispatch" might be better.
Routes does not dispatch [i.e., instantiate the class and call the
method]. Routes just parses the URL and returns a dict of variables.
So maybe "Routes-like URL parsing" would be more accurate.
> MO: we could add our own
middleware by wrapping the WSGI application before returning it
> CM: Note that I *think* it's Ben's intent to encourage people to
add middleware by putting it into a ``pipeline`` stanza in the
Paste ``.ini`` file rather than by adding it imperatively by
wrapping the result of ``make_wsgi_app``. Not that the latter
can't be done, but it makes things like "paster shell" impossible
to write without additional framework to handle excluding
middleware when a shell is run.
I saw that pipeline in an example INI Ben showed me, but I didn't
realize he wanted to do it across the board. I have never liked IN I
pipelines; they're hard to understand and non-Python syntax (which
means it could be hard to trace why it can't find one of the
components, for instance). What middleware does "paster shell"
exclude?
Ben, what do you want me to do here?
> CM: I suppose an introductory paragraph about BFG would be helpful somewhere in here.
I punted on that because I'm still figuring out how to present it. It
may go on another page. I want to separate the basic introduction, the
application code, a detailed look of differences between Pylons 1 and
Pylons 2, and enough BFG to understand the BFG manual and how it
relates to Pylons. I.e.,which parts Pylons uses and which parts are
alternative application styles that Pylons doesn't use. Those
Configurator.add_* methods are one example.
> CM: the ability to share a well-known table-space for
user data
What does this mean?
> CM: the ability to use a common "main template" for theming
That's good. the more we can describe the practical benefits, the
better. There are several things like theming and a grandparent site
template for subapplications that Pylons users haven't done because
they're so cumbersome in the old structure.
I see repoze.bfg.jinja2 exists in PyPI. At some point we'll need a
repoze.bfg.genshi in case people have existing templates that don't
work with Chameleon.
> CM:
+ [filter:evalerror]
+ use = egg:WebError#evalerror
+
+ [pipeline:main]
+ pipeline = evalerror
So I guess I'll have to explain pipelines right up front.
What's the best way to figure out the entry point name to use and the
right syntax, for any arbitrary entry point?
What about logging? Are we keeping the logging-in-the-same-INI-file
paradigm? Whose responsibility is it to activate it?
I suppose a logging configuration may not belong in the minimal
application, but in that case I'd have to provide the code to paste
in. (Maybe using paste.translogger as a sample middleware that uses
logging.)
On the other hand, it can be argued that logging is so central to
everything, it belongs in the minimal application.
Especially because libraries may log, and there really should be
handlers and formatters already set up for it in that case.
--
Mike Orr <slugg...@gmail.com>
Chris McDonough
> Comments to Chris' comments.
>
>> MO: The static files are moved; they’re in the templates directory rather than in “hello/static”.
>
>> CM: I think we'll want to move the static files out of the
> templates directory and up into a peer of the templates directory.
>
> I made a mistake here. The traditional Pylons location is
> hello/public. not hello/static .So it's up to Ben whether to rename
> the location. There are arguments both ways. "static" is a more
> standard term, but "public" is backward compatible.
>
> But why are they in hello/templates/static in the first place? Is that
> what BFG normally does? It surprised me because they're not templates.
> But I can vaguely see the logic if you consider "template" and
> "renderer" in a broader sense than just template engines.
It was just a mistake. There hasn't been a lot of thought put into the
paster templates. I've moved the static directory up to be a peer of
templates; Ben can decide whether he wants to rename it to public.
> Ben, what do you want to do with static files? I'm assuming they're
> staying where they are for now.
>
>> MO: Routes-like traversal is built into BFG
>
>> CM: "routes-like traversal" is probably not the right term.
> "Routes-like pattern-based URL dispatch" might be better.
>
> Routes does not dispatch [i.e., instantiate the class and call the
> method]. Routes just parses the URL and returns a dict of variables.
> So maybe "Routes-like URL parsing" would be more accurate.
Anything that doesn't have "traversal" in it would be good, because that
word is used by BFG to mean something entirely different.
>> MO: we could add our own
> middleware by wrapping the WSGI application before returning it
>
>> CM: Note that I *think* it's Ben's intent to encourage people to
> add middleware by putting it into a ``pipeline`` stanza in the
> Paste ``.ini`` file rather than by adding it imperatively by
> wrapping the result of ``make_wsgi_app``. Not that the latter
> can't be done, but it makes things like "paster shell" impossible
> to write without additional framework to handle excluding
> middleware when a shell is run.
>
> I saw that pipeline in an example INI Ben showed me, but I didn't
> realize he wanted to do it across the board. I have never liked IN I
> pipelines; they're hard to understand and non-Python syntax (which
> means it could be hard to trace why it can't find one of the
> components, for instance). What middleware does "paster shell"
> exclude?
It exludes every piece of middleware (or should).
Note that the following currently this works in lieu of "paster shell",
assuming you've named your "newminimal" project "Hello":
paster bfgshell development.ini Hello
Or, for reasons I don't quite understand, you might need:
paster --plugin=repoze.bfg bfgshell development.ini Hello
This works because the second arg to "paster bfgshell", "Hello", is the
"real" application object as defined in the Paste .ini file. It will
not work if Hello is wrapped in any middleware, however.
> Ben, what do you want me to do here?
>
>> CM: I suppose an introductory paragraph about BFG would be helpful somewhere in here.
>
> I punted on that because I'm still figuring out how to present it. It
> may go on another page. I want to separate the basic introduction, the
> application code, a detailed look of differences between Pylons 1 and
> Pylons 2, and enough BFG to understand the BFG manual and how it
> relates to Pylons. I.e.,which parts Pylons uses and which parts are
> alternative application styles that Pylons doesn't use. Those
> Configurator.add_* methods are one example.
>
>> CM: the ability to share a well-known table-space for
> user data
>
> What does this mean?
Sharing data between applications, mostly.
>> CM: the ability to use a common "main template" for theming
>
> That's good. the more we can describe the practical benefits, the
> better. There are several things like theming and a grandparent site
> template for subapplications that Pylons users haven't done because
> they're so cumbersome in the old structure.
Sorry if it wasn't clear, but for the record, when I mentioned "a shared
main template", it was in the context of saying that Pylons *isn't* the
right layer at which a normal user should try to compose a system out of
a bunch of random pre-written third-party applications.
IMO, allowing a user to plug in some random third-party application and
making it easy to have a common main template (or other "theme") between
all such applications, and mediating access to a data store that must be
shared between arbitrary applications is something that Pylons should
just not try to do. Instead, a higher-level system should be built atop
Pylons that allows for a saner composition of reusable applications (one
with enough constraints in it to make the result of plugging them
together more predictable).
On the other hand, Pylons *should* (and does) allow for a single
existing application to be extended and overridden, and it does allow a
composition of non-reusable applications to be created and deployed by a
*single* developer. It just isn't the piece that will allow an
"integrator" to collect up a bunch of applications that a bunch of
random people have written and plug them all together to form a cohesive
system; it doesn't have enough constraints to allow that to happen in a
sane way (the Django folks are hitting this wall right now, and I don't
think we want to follow them down that path).
> I see repoze.bfg.jinja2 exists in PyPI. At some point we'll need a
> repoze.bfg.genshi in case people have existing templates that don't
> work with Chameleon.
I think Ben is deciding what he wants to do about that.
>
>
>> CM:
> + [filter:evalerror]
> + use = egg:WebError#evalerror
> +
> + [pipeline:main]
> + pipeline = evalerror
>
> So I guess I'll have to explain pipelines right up front.
>
> What's the best way to figure out the entry point name to use and the
> right syntax, for any arbitrary entry point?
It's egg:<DistributionName>#entrypointname
The entry point names for a given package are in
EGG-INFO/entrypoints.txt .
Paste defaults to using the name "main" as the entry point name, so
these two Paste names are equivalent:
egg:Hello#main
and
egg:Hello
> What about logging? Are we keeping the logging-in-the-same-INI-file
> paradigm? Whose responsibility is it to activate it?
Probably should still live in INI file.
>
> I suppose a logging configuration may not belong in the minimal
> application, but in that case I'd have to provide the code to paste
> in. (Maybe using paste.translogger as a sample middleware that uses
> logging.)
>
> On the other hand, it can be argued that logging is so central to
> everything, it belongs in the minimal application.
> Especially because libraries may log, and there really should be
> handlers and formatters already set up for it in that case.
Should be fine to add that configuration there.
- C
Ian Bicking
> I saw that pipeline in an example INI Ben showed me, but I didn't> realize he wanted to do it across the board. I have never liked IN IIt exludes every piece of middleware (or should).
> pipelines; they're hard to understand and non-Python syntax (which
> means it could be hard to trace why it can't find one of the
> components, for instance). What middleware does "paster shell"
> exclude?
Note that the following currently this works in lieu of "paster shell",
assuming you've named your "newminimal" project "Hello":
paster bfgshell development.ini Hello
Or, for reasons I don't quite understand, you might need:
paster --plugin=repoze.bfg bfgshell development.ini Hello
This works because the second arg to "paster bfgshell", "Hello", is the
"real" application object as defined in the Paste .ini file. It will
not work if Hello is wrapped in any middleware, however.
I had always suggested to Ben that paster shell should run a fake request to a fake responder, but he never took me up on that. Since things are being rethought maybe that can be rethought too. Like:
class PasterShell:
def run(self):
app = getapp()
req = Request.blank('/PasterShell')
req.environ['paste.paster_shell'] = True
resp = req.get_response(app)
Then in the routing special case that environmental variable and/or path. You'd want to do this wherever it's closest to the app. E.g., PylonsApp? I don't know what that will be in the new system. But the controller would just call cmd, ipython, whatever. Both request and response are superfluous, but you will be entirely within the context of any middleware, configuration, etc. You could implement all commands this way if you wanted to (shell, setup-app, etc).
--
Ian Bicking | http://blog.ianbicking.org
Chris McDonough
> On Sep 12, 2010, at 3:13 PM, Chris McDonough wrote:
>
>>> What's the best way to figure out the entry point name to use and the
>>> right syntax, for any arbitrary entry point?
>>
>> It's egg:<DistributionName>#entrypointname
>>
>> The entry point names for a given package are in
>> EGG-INFO/entrypoints.txt .
>>
>> Paste defaults to using the name "main" as the entry point name, so
>> these two Paste names are equivalent:
>
>
> Right now, its kind of a pain to:
> A) See what middleware is available with stock Pylons
> B) Figure out what the heck the entry point name is, without which, you can't use it in the INI file, I usually have to read the source to find the damn entry point names, we should save our users from doing that
> C) Know what options each piece of middleware can take in the INI file
Most of this is already handled via "paster points", e.g. do
"env/bin/paster points paste.filter_app_factory" in a virtualenv that
has Pylons installed. What that doesn't do is give you the "egg name",
although you don't really need the egg name; it gives you the dotted
name to the middleware factory, which can also be used.
- C
Ben Bangert
>> What's the best way to figure out the entry point name to use and the
>> right syntax, for any arbitrary entry point?
>
> It's egg:<DistributionName>#entrypointname
>
> The entry point names for a given package are in
> EGG-INFO/entrypoints.txt .
>
> Paste defaults to using the name "main" as the entry point name, so
> these two Paste names are equivalent:
Also, not sure what type of license Ian has his Paste docs under, but I want to pull in the necessary information about how to configure INI files, such that a user doesn't have to go to the PasteDeploy docs to look-up how to set a filter middleware, etc. Having this in one Configuration section of the Pylons docs also means we can provide a list of all the available middleware (and entry point names!) so that someone could look through, see what they want in their stack, and easily add it to the appropriate INI file (cause the dev.ini will prolly differ from the prod.ini).
Right now, its kind of a pain to:
A) See what middleware is available with stock Pylons
B) Figure out what the heck the entry point name is, without which, you can't use it in the INI file, I usually have to read the source to find the damn entry point names, we should save our users from doing that
C) Know what options each piece of middleware can take in the INI file
I think a good way to separate the distinction is that the INI file is where settings and the application wrappers are configured, which can differ between production, staging, testing, and deployment, while the make_app is where the application itself is configured.
- Ben
Ben Bangert
> Most of this is already handled via "paster points", e.g. do
> "env/bin/paster points paste.filter_app_factory" in a virtualenv that
> has Pylons installed. What that doesn't do is give you the "egg name",
> although you don't really need the egg name; it gives you the dotted
> name to the middleware factory, which can also be used.
Yea, that doesn't really recommend which ones to use though. I wanted to editorialize a little. :)
Mike Orr
adjusted the guide for those and for the new location of the static
files. I adjusted the text for describing Routes and CM's other
points.
--
Mike Orr <slugg...@gmail.com>
Mike Orr
We'll have to look at this later. My main application at work is a
collection of independent components that share the same domain and
login. I've kept it as one big application because Pylons is so
unfriendly to nested apps (how to integrate the templates and
routing?), and it was moreso when the app was written two years ago.
So I have a site template, section templates, and page templates,
which all inherit from each other. Anyway, I think we should provide
suggestions on how to compose apps like this.... later.
>> What about logging? Are we keeping the logging-in-the-same-INI-file
>> paradigm? Whose responsibility is it to activate it?
>
> Probably should still live in INI file.
>> I suppose a logging configuration may not belong in the minimal
>> application, but in that case I'd have to provide the code to paste
>> in. (Maybe using paste.translogger as a sample middleware that uses
>> logging.)
>>
>> On the other hand, it can be argued that logging is so central to
>> everything, it belongs in the minimal application.
>> Especially because libraries may log, and there really should be
>> handlers and formatters already set up for it in that case.
>
> Should be fine to add that configuration there.
I guess that means myapp/__init__.py will have to initialize the
logging. Because who else will?
This might be good to make the logging activation explicit. One
problem with "paster serve" is nobody can figure out where logging is
activated or why it doesn't automatically work with "paster shell" or
custom commands. It gives the impression that Paste activates the
logging as a basic Paste service, but it doesn't, "paster serve" or
something below it does.
--
Mike Orr <slugg...@gmail.com>
Mike Orr
> Mike, this is a great first step!
:) :)
> I think your "hello, world" in Pylons 2 should probably be adapted into a "Learning Pylons 2 for the Pylons 1 User" type document. As it does a great job explaining differences in terminology, where things come from (which is good for more advanced users, but maybe can be excluded for someone just wanting to know how to do things the new way), and some of the advantages of the new setup.
I'll move some of the background paragraphs into separate pages. But
this page will focus on the minimal app.
Do you have any sample applications in both Pylons 1 and Pylons 2 that
I can include? The more sophistocated one with multiple actions and a
redirect may be a start.
Where is pylons.url now? request.url?
I notice that ``request[foo]`` shadows ``request.environ[foo]``. Has
WebOb always done that?
> For the general documentation, here are the directions Chris and I were thinking would be a big priority:
>
> - Integrated documentation
> This means that *everything* one needs to write and use Pylons 2 will be in a single spot. This will involve documenting everything that we expect a user to use, in the main Pylons docs. All the configuration options and how sessions work (from Beaker), all the methods they would want to use of the Request and Response object (from Pylons, BFG, and WebOb), all the docs on how to register handlers, views, etc. (from BFG/Pylons), how to test an application and the methods/object docs, and probably all the important bits someone will use in Mako templates.
That may be too much to manage this phase. But I can link to the manuals.
I guess I can make a Makefile that checks out the repositories of all
the dependencies, and let Sphinx recursively build all the manuals. It
started doing that with BFG and Pylons unexpectedly until I excluded
their parent directory in conf.py.
> - Avoid mentioning what package provides what bit for the most part
> This helps make the entire framework "feel" like an integrated whole. And the majority of the time, no user really cares that the Request/Response are WebOb subclasses, that the Pylons Configurator is a BFG subclass, that the events they imported from Pylons are shadow points for BFG ones, etc. Maybe in an Advanced chapter, where the components are dived into in detail, then the background of where these things originate will be mentioned. For the new and average user though, they just make the docs longer, and add unnecessary information that makes it feel more hacky. (I know that right now the main reason all the origins are mentioned is mainly because Pylons avoids re-documenting them, which will no longer be the case.)
I think we need the distinction for the transitional phase. Existing
Pylons users need to understand where everything is. So they can find
the docstrings in the source code, for one thing. And I, as a reader,
would certainly want to know where the different Request methods come
from. Otherwise it's too confusing, especially if I'm trying to figure
out how Request changed.
Later we can de-emphasize the packages, and make the documentation all
Django-like. And get somebody to publish a new book! Hmm, I wonder if
James, Noah, or Alfredo would want to mull that one over. But much of
the content would come from this open source project, so it would be a
different situation than a Manning/Apress/Packt book. We'd have to
retain the copyright up front. I wonder which publishers would be
willing to be just a printer and marketer.
> The package list you note there has me thinking that maybe we can drop decorator, FormEncode, Routes, and WebHelpers from the Pylons dependencies. This means that the things using it in the Pylons code-base will need to be wrapped in try/except imports so that everything still works for legacy apps with Pylons 2.
Decorator is really a basic Python utility that belongs in the stdlib.
It would be silly to drop it now if we might need it again later.
You talked about a separate Pylons-FormEncode package. Although I
don't know what it would include besides the dependency. Buit
WebHelpers could go with that.
What try/excepts? I don't think there's anything in the Pylons core or
application template that imports FormEncode or WebHelpers. Routes is
more central, of course. What's wrong with a Pylons1-Compatibility
package like I suggested earlier. Just tell people they need to
install that if they want to run a Pylons 1 applicaton under Pylons 2.
It's similar to Pylons 0.10, which keeps compatibility code, but done
in a different way.
But if the try/excepts have to be in the application, we're kind of
screwed, because we can't go auto-modifying people's applications and
breaking them.
The whole issue of excess dependencies will really have to be dealt
with at another level. BFG pulls in a lot of things that aren't
relevant to a typical Pylons application, like Chameleon. App Engine
users will certainly be interested in what they can exclude from
uploading. I think we can worry about that later, to provide a list or
regexp of files that can be excluded.
--
Mike Orr <slugg...@gmail.com>
Ben Bangert
> I'll move some of the background paragraphs into separate pages. But
> this page will focus on the minimal app.
>
> Do you have any sample applications in both Pylons 1 and Pylons 2 that
> I can include? The more sophistocated one with multiple actions and a
> redirect may be a start.
Not at the moment.
> Where is pylons.url now? request.url?
from pylons.url import route_url
Then just, route_url(request, 'route_name', **extra_args). It works largely like the BFG route_url, except honors an additional URL generator option that a route can have. This is how I have a sub-domain setup implemented. I'll prolly have to move route_url elsewhere, as there's a 'url' object hanging out in pylons/__init__.py.
> That may be too much to manage this phase. But I can link to the manuals.
>
> I guess I can make a Makefile that checks out the repositories of all
> the dependencies, and let Sphinx recursively build all the manuals. It
> started doing that with BFG and Pylons unexpectedly until I excluded
> their parent directory in conf.py.
Ah, unfortunately that won't be good enough. Chris and I had chatted about trying to do something with Makefiles so that things would be included, but unfortunately this means that the included stuff retains reference to its own docs. This creates a very hacked up reading experience that is not going to be pleasant.
> I think we need the distinction for the transitional phase. Existing
> Pylons users need to understand where everything is. So they can find
> the docstrings in the source code, for one thing. And I, as a reader,
> would certainly want to know where the different Request methods come
> from. Otherwise it's too confusing, especially if I'm trying to figure
> out how Request changed.
Well, I guess I just mean that I wouldn't waste the reader's time explaining the history of every object they might want to use, vs just saying, here is where you import the Request from, and then linking to its API docs. Our API docs can mention where it comes from, which methods come from where, etc. There's no reason to bog down the documentation explaining things that the reference API can explain as it documents the objects. This also means that as we document *everything* we expect Pylons users to have, we can include doc strings with Sphinx as needed, and editorialize them ourself as well. Sphinx makes it quite easy to ignore doc strings, or ignore module docs and supply your own. That'd be a good place to add in additional info about what comes from where, etc.
If the docs are written with the expectation of a first-time Pylons user, then an existing Pylons user should be helped just as much to see where things are. I don't think de-emphasizing all the packages involved means that someone wouldn't know where something they need to use it. It just means we wouldn't waste the users time explaining the history of XX, or why ZZ was done.
Keep the focus on how to do it, where the objects they need to import are, and point them to the reference API for said objects. I plan on adding a "Design Defense" page similar to what repoze.bfg has, that explains the 'why' of the design decisions in Pylons, so we can avoid repeating explanations throughout the docs, which should keep a tight focus on what the developer needs to know to get going.
Then have a section for migrating users that explains what moved where, how to use new features with an existing app using the legacy_view, etc.
For example, take sessions, Pylons 2 has an add_sessions that sets them up, and a request.session object they make use of for the session. I would imagine the Sessions section would indicate that you use add_sessions, how to use the request.session object, how to change the configuration options, and then send the user to the Session API docs. The Session API docs would include the complete set of configuration options, include any relevant info on the package (Beaker) that actually implements the sessions, and then have all the relevant module docs someone wanting all the details would need.
This keeps the "How to use Sessions" bit short, concise, and fast for a developer to get going with, and then leaving the Reference API section to fully document the additional configuration options, what objects come from where, what type they are, etc. The existing Pylons user will generally jump straight to the Reference section when they need to know about an object, or its methods, or configuring it since they already know *how to use* it.
Alternatively, a documentation style that might be worth trying, is what Mike Bayer has done with the latest version of the SQLAlchemy docs, which I'm kind of liking. That is, we'd have a "Pylons Overview" chapter, that includes a short bit on how to do "all the standard things" a Pylons user would want to do. Installation, Hello World, Using Sessions, etc. Each one then links to the full chapter, and the full chapter goes into all the details, and includes the API docs in-line.
Sphinx makes either style pretty easy, so its kind of tempting to try out the approach Mike Bayer is doing.
> Decorator is really a basic Python utility that belongs in the stdlib.
> It would be silly to drop it now if we might need it again later.
The only purpose of decorator is to ensure the function retains the same signature. Having code inspecting things for signatures is rather annoying to begin with, and has frustrated a lot of Pylons users writing decorators. I should hope we won't need it later. :)
> You talked about a separate Pylons-FormEncode package. Although I
> don't know what it would include besides the dependency. Buit
> WebHelpers could go with that.
I think it would include helpers that can make the assumption that you're using Formencode and Pylons. @validate is an example of something that would go in there, or since @validate is so problematic, some other Pylons appropriate utility functions.
> What try/excepts? I don't think there's anything in the Pylons core or
> application template that imports FormEncode or WebHelpers. Routes is
> more central, of course. What's wrong with a Pylons1-Compatibility
> package like I suggested earlier. Just tell people they need to
> install that if they want to run a Pylons 1 applicaton under Pylons 2.
> It's similar to Pylons 0.10, which keeps compatibility code, but done
> in a different way.
I think there are some imports in Pylons of FormEncode and WebHelpers actually. The secure form stuff from Pylons decorators makes a WebHelpers import, as it also makes a FormEncode import.
We can't make a separate pylons-legacy package, because then all the stuff they're expecting to import from Pylons.... wouldn't be there. And I want Pylons 2 not to cause someone to have to change their project unless they're using new things.
> But if the try/excepts have to be in the application, we're kind of
> screwed, because we can't go auto-modifying people's applications and
> breaking them.
No, I meant in the places where Pylons is importing WebHelpers and FormEncode, it wraps the imports in try/excepts so that the legacy decorators will only work if the user has installed FE/WebHelpers, vs having it as a Pylons requirement.
- Ben
Ben Bangert
> Can it be made into a request method so you don't have to pass the
> request object? That would be more OO.
Sure, request.url though makes it ambiguous if its the request URL vs a url function. Ian called it request.link in his example app using Routes, so maybe something like that?
> Or do you have to paste the markup text from the subprojects and
> convert all "autoclass" to "class" by hand? The problem with this is
> it would gradually drift out of date unless you went through every few
> months looking for differences between your docs and the originals,
> which would take a lot of time.
Yes, you paste in the ones where appropriate (some of the sub-projects have none, or little docs, so we'd have to write those). This is part of the main issue btw, when we punt on doing it and just tell people to "go look at that", and then the docs we pointed them to are incomplete, fail to mention how it applies in the context of the framework, etc. we just.... fail. Yes, it takes time to document the big picture and its parts effectively, in some cases we can copy/paste or still have Sphinx auto-generate an objects doc from the doc-string still, but in other cases we'll have to fill in gaps.
Regardless of how its done, using and documenting Pylons as it consists of other projects requires time to keep the docs up to date as dependencies change. We're not doing anyone a favor by not addressing this issue at the moment. I don't think this means we need to document *all* of every single project, but we need to copy the docs or document anything ourself which we expect a Pylons developer to use that comes with Pylons.
Except for BFG, the other dependencies are pretty much 'done' though, their docs aren't changing as they're not really changing anymore.
> Easy for you maybe. I still have to pour through the Sphinx manual
> sometimes wishing it would explain more clearly how to do something.
> If we could sprint together it would be easier.
Agreed.
> I'm inclined to agree with James, that explaining it at a non-Python
> or non-web-developer level triples the workload. (Once to write the
> new text, and again to test all the examples on platforms you don't
> use.) Anyway, once we get the higher-level text squared away, the
> newbie text will be just a matter of filling in the background. And
> James' book provides a guide on what the newbie needs explained.
Oh, I'd never aim it at a total non-Python or non-webdev. That's what books are for. Pylons documentation is for:
1) How do I do XXX with Pylons?
2) What are all the options to do XXX with Pylons?
3) How do I extend and utilize other web dev patterns with Pylons?
These leads to a set of docs that are generally fairly short and concise to go over how to do various things (prolly a Quick Start / Overview), where each section hyperlinks them to the more extensive web dev patterns of that topic, all of which link to the reference docs (which show all the options).
Once you know how add_sessions works, there's really no point in wasting space in the narrative docs explaining each option, when just a list of all the options and what they do would work just as well. The latter being the reference API docs.
> OK, maybe I can outsource that part to you. The first page ("Intro")
> starts to get into that (at least re the changes since Pylons 1), but
> it just takes so long to write with all the necessary background that
> I postponed it. Plus, you guys can remember the new practical
> features better than I can.
Sure, sounds good.
> I don't think I've encountered legacy_view yet. How does it work?
There's a legacy pylons template that shows it. It essentially lets you hook up an existing Pylons app with zero changes, and then start adding new handlers with the Configurator.
> BTW, where is the cache?
No where right now. Technically all you need to do is import the cache module from Beaker, set the options, and use @cache_region as desired. I should prolly add a setup function for that on the configurator and an import in Pylons though, as that'll make it feel more cohesive.
> Will there be an app_globals? I'd also suggest a thread_locals (or
> app_globals.locals), because uses keep wondering where to put
> threadlocals and end up reinventing it themselves.
Technically, those can be added to the application registry as 'utilities', but it'd make sense maybe to have a config arg that lets you designate some functions that want to setup 'global' type objects, and when configuration is completely done, it'd call those functions and let them set it up. That'd also ensure that they're only setting up the 'app globals' when all the config information is available.
> I was disconcerted when I looked at the SQLAlchemy docs last week and
> the entire API section seemed to be missing. I actually thought it was
> a bug and figured it would come back in a few days. Then I noticed
> that the API docs were integrated with the narrative sections rather
> than all together. I'm not sure if I like it or not. Do all the API
> sections have narrative sections? Because sometimes I need to look up
> an undocumented method, e.g., to access column metadata in a program.
Yea, its a tough one. Let's stick with having a separate Reference API section for now. I should note I have no plan on having it organized how Sphinx does 'modules' right now. I think it kind of sucks how Sphinx just makes an alphabetical listing of all the modules. Instead, I'm going to organize the API section the same as the narrative... by topic. So there'd be a 'Sessions' section in the API docs, and that lists all the functions/classes/modules you should need to know about for everything that is 'session' related. I get the distinct impression this would help people find the right module/class/function, since right now ppl end up asking these questions on the Pylons channel and other ppl have to find it and link them to it.
> Do you mean just changing the message to "ImportError: please install
> the 'formencode' package", or something more elaborate?
Just that, so that if they had old code that wanted to use it, they should install it.
Cheers,
Ben
Mike Orr
> Also, not sure what type of license Ian has his Paste docs under, but I want to pull in the necessary information about how to configure INI files, such that a user doesn't have to go to the PasteDeploy docs to look-up how to set a filter middleware, etc.
I'm not worrying about licenses now. I assume the licenses will be
adjusted before release to allow any parts to be pasted into the
Pylons guide. I thought that was already the case anyway. Everything's
MIT-based, and if there is anything that's GPL, we're releasing the
documentation sources anyway so it shouldn't matter.
--
Mike Orr <slugg...@gmail.com>
Chris McDonough
> I notice that ``request[foo]`` shadows ``request.environ[foo]``. Has
> WebOb always done that?
This is a behavior of the repoze.bfg subclass of WebOb (in
repoze.bfg.request.Request). It's only for backwards compatibility with
applications written for version 1.0 of BFG, and shouldn't be relied
upon in user applications; it is not part of the request API and the
behavior will be removed in BFG 1.4, or possibly sooner.
There's a bit of info about that for BFG here:
http://docs.repoze.org/bfg/1.3/tutorials/gae/index.html#zipping-files-via-pip
Chris McDonough
>>
>> Probably should still live in INI file.
>
>>> I suppose a logging configuration may not belong in the minimal
>>> application, but in that case I'd have to provide the code to paste
>>> in. (Maybe using paste.translogger as a sample middleware that uses
>>> logging.)
>>>
>>> On the other hand, it can be argued that logging is so central to
>>> everything, it belongs in the minimal application.
>>> Especially because libraries may log, and there really should be
>>> handlers and formatters already set up for it in that case.
>>
>> Should be fine to add that configuration there.
>
> I guess that means myapp/__init__.py will have to initialize the
> logging. Because who else will?
I figured it would just go in the .ini file as before, and PasteDeploy
would initialize it as always.
> This might be good to make the logging activation explicit. One
> problem with "paster serve" is nobody can figure out where logging is
> activated or why it doesn't automatically work with "paster shell" or
> custom commands. It gives the impression that Paste activates the
> logging as a basic Paste service, but it doesn't, "paster serve" or
> something below it does.
Stdlib logging configuration is horrid, no matter how you slice it
really. Maybe just a little howto for paster shell about how to
configure logging explicitly from the development.ini file?
- C
Mike Orr
>> I guess that means myapp/__init__.py will have to initialize the
>> logging. Because who else will?
>
> I figured it would just go in the .ini file as before, and PasteDeploy
> would initialize it as always.
Oh, duh, I didn't realize it would keep doing that, but of course it would.
--
Mike Orr <slugg...@gmail.com>
Chris McDonough
> On Sep 13, 2010, at 12:09 AM, Mike Orr wrote:
>
>> I'll move some of the background paragraphs into separate pages. But
>> this page will focus on the minimal app.
>>
>> Do you have any sample applications in both Pylons 1 and Pylons 2 that
>> I can include? The more sophistocated one with multiple actions and a
>> redirect may be a start.
>
> Not at the moment.
Blaise Laflamme began this project:
http://bitbucket.org/blaf/pylonswiking/overview . It's a
transliteration BFG wiki example into "newpylons". The code is in
"src", the rest of it is RST documentation.
- C
Mike Orr
>> Where is pylons.url now? request.url?
>
> from pylons.url import route_url
>
> Then just, route_url(request, 'route_name', **extra_args). It works largely like the BFG route_url, except honors an additional URL generator option that a route can have. This is how I have a sub-domain setup implemented. I'll prolly have to move route_url elsewhere, as there's a 'url' object hanging out in pylons/__init__.py.
Can it be made into a request method so you don't have to pass the
request object? That would be more OO.
>> That may be too much to manage this phase. But I can link to the manuals.
>>
>> I guess I can make a Makefile that checks out the repositories of all
>> the dependencies, and let Sphinx recursively build all the manuals. It
>> started doing that with BFG and Pylons unexpectedly until I excluded
>> their parent directory in conf.py.
>
> Ah, unfortunately that won't be good enough. Chris and I had chatted about trying to do something with Makefiles so that things would be included, but unfortunately this means that the included stuff retains reference to its own docs. This creates a very hacked up reading experience that is not going to be pleasant.
How would you do this then? If I have all the source repositories in a
subdirectory and exclude them from auto-building, can I still link to
subproject .rst files and it'll include all their dependencies? Does
".. autoclass" work through subprojects?
Or do you have to paste the markup text from the subprojects and
convert all "autoclass" to "class" by hand? The problem with this is
it would gradually drift out of date unless you went through every few
months looking for differences between your docs and the originals,
which would take a lot of time.
> Sphinx makes it quite easy to ignore doc strings, or ignore module docs and supply your own. That'd be a good place to add in additional info about what comes from where, etc.
Easy for you maybe. I still have to pour through the Sphinx manual
sometimes wishing it would explain more clearly how to do something.
If we could sprint together it would be easier.
> If the docs are written with the expectation of a first-time Pylons user, then an existing Pylons user should be helped just as much to see where things are.
I'm inclined to agree with James, that explaining it at a non-Python
or non-web-developer level triples the workload. (Once to write the
new text, and again to test all the examples on platforms you don't
use.) Anyway, once we get the higher-level text squared away, the
newbie text will be just a matter of filling in the background. And
James' book provides a guide on what the newbie needs explained.
> Keep the focus on how to do it, where the objects they need to import are, and point them to the reference API for said objects. I plan on adding a "Design Defense" page similar to what repoze.bfg has, that explains the 'why' of the design decisions in Pylons, so we can avoid repeating explanations throughout the docs, which should keep a tight focus on what the developer needs to know to get going.
OK, maybe I can outsource that part to you. The first page ("Intro")
starts to get into that (at least re the changes since Pylons 1), but
it just takes so long to write with all the necessary background that
I postponed it. Plus, you guys can remember the new practical
features better than I can.
> Then have a section for migrating users that explains what moved where, how to use new features with an existing app using the legacy_view, etc.
I don't think I've encountered legacy_view yet. How does it work?
BTW, where is the cache?
Will there be an app_globals? I'd also suggest a thread_locals (or
app_globals.locals), because uses keep wondering where to put
threadlocals and end up reinventing it themselves.
> Alternatively, a documentation style that might be worth trying, is what Mike Bayer has done with the latest version of the SQLAlchemy docs, which I'm kind of liking. That is, we'd have a "Pylons Overview" chapter, that includes a short bit on how to do "all the standard things" a Pylons user would want to do. Installation, Hello World, Using Sessions, etc. Each one then links to the full chapter, and the full chapter goes into all the details, and includes the API docs in-line.
I was disconcerted when I looked at the SQLAlchemy docs last week and
the entire API section seemed to be missing. I actually thought it was
a bug and figured it would come back in a few days. Then I noticed
that the API docs were integrated with the narrative sections rather
than all together. I'm not sure if I like it or not. Do all the API
sections have narrative sections? Because sometimes I need to look up
an undocumented method, e.g., to access column metadata in a program.
> No, I meant in the places where Pylons is importing WebHelpers and FormEncode, it wraps the imports in try/excepts so that the legacy decorators will only work if the user has installed FE/WebHelpers, vs having it as a Pylons requirement.
Do you mean just changing the message to "ImportError: please install
the 'formencode' package", or something more elaborate?
--
Mike Orr <slugg...@gmail.com>
Ben Bangert
> Can it be made into a request method so you don't have to pass the
> request object? That would be more OO.
property.
> Or do you have to paste the markup text from the subprojects and
> convert all "autoclass" to "class" by hand? The problem with this is
> it would gradually drift out of date unless you went through every few
> months looking for differences between your docs and the originals,
> which would take a lot of time.
other docs.
> I'm inclined to agree with James, that explaining it at a non-Python
> or non-web-developer level triples the workload. (Once to write the
> new text, and again to test all the examples on platforms you don't
> use.) Anyway, once we get the higher-level text squared away, the
> newbie text will be just a matter of filling in the background. And
> James' book provides a guide on what the newbie needs explained.
some clue about web dev, and knows Python decently. A book is the
place for more expansive documentation.
> OK, maybe I can outsource that part to you. The first page ("Intro")
> starts to get into that (at least re the changes since Pylons 1), but
> it just takes so long to write with all the necessary background that
> I postponed it. Plus, you guys can remember the new practical
> features better than I can.
> I don't think I've encountered legacy_view yet. How does it work?
configurator for a new style Pylons app.
> BTW, where is the cache?
config.add_cache(). This was just recently added to trunk.
> Will there be an app_globals? I'd also suggest a thread_locals (or
> app_globals.locals), because uses keep wondering where to put
> threadlocals and end up reinventing it themselves.
will hold the things you would've put in app_globals.
> I was disconcerted when I looked at the SQLAlchemy docs last week and
> the entire API section seemed to be missing. I actually thought it was
> a bug and figured it would come back in a few days. Then I noticed
> that the API docs were integrated with the narrative sections rather
> than all together. I'm not sure if I like it or not. Do all the API
> sections have narrative sections? Because sometimes I need to look up
> an undocumented method, e.g., to access column metadata in a program.
organized differently than Sphinx generally does it. I.e., rather than
just an unhelpful module listing of all the various bits, we'll
organized the API docs by topic. Caching, Sessions, Database, Request/
Response, Exceptions, etc. I think that'd make the module API much
easier to go through for detail on all the options various methods/
classes can take.
> Do you mean just changing the message to "ImportError: please install
> the 'formencode' package", or something more elaborate?
formencode is present. So that its not actually required to install
formencode.
On a side-note, when using the "renderer=" approach to rendering a
template, the dict results go into the template global namespace....
should they instead go into tmpl_context?
Cheers,
Ben
Ben Bangert
BTW, for anyone else that just saw this message appear apparently out of the blue, Google Groups does have the full thread but failed to e-mail it out. To catch up, just go to:
http://groups.google.com/group/pylons-devel/browse_thread/thread/cf357889d81e37b3
- Ben
Chris McDonough
> Yea, we're going to have to compose copy/paste to an extent, from the
> other docs.
I've indicated to Ben that I am willing to genericize the BFG docs to
some extent by not linking to internal stuff in API documentation
needlessly. But I doubt this will really do much good; there are places
where those kinds of links are just required. It will probably boil
down to everything needing to be cutnpasted.
For what it's worth, we tend to keep extremely detailed change logs in
BFG. When I change documentation, I make a note about which docs I
changed. As a result, while it won't be falling-off-a-log easy to keep
cutnpasted Pylons docs in sync with the BFG docs, and it will require a
lot of effort, it should at least be theoretically possible if someone
pays attention to the BFG changelogs, and I'm more than willing to help
explain changes in detail to whomever is assigned that job.
> On a side-note, when using the "renderer=" approach to rendering a
> template, the dict results go into the template global namespace....
> should they instead go into tmpl_context?
My $.02.. if you don't have a threadlocal tmpl_context around for
people to jam values onto/into, it'd just confuse people if the dict
values they returned from a view weren't passed as top-level names to
the template, and instead were made available as the subkey
"tmpl_context".
- C
Ben Bangert
> My $.02.. if you don't have a threadlocal tmpl_context around for
> people to jam values onto/into, it'd just confuse people if the dict
> values they returned from a view weren't passed as top-level names to
> the template, and instead were made available as the subkey
> "tmpl_context".
Well, there is a tmpl_context created on the request, that is available in templates as well. So it is around, created per-request as in Pylons 1.0, for ppl to add things to. So it might seem like a disconnect when someone add's things to tmpl_context in one case, but then it gets dropped in as a template global under the 'renderer=' scenario. Having everything a person wants to pass in, always go in under tmpl_context seems more consistent.
- Ben
Chris McDonough
Drawing an equivalence between Pylons 1 and 2 by having a
request.tmpl_context seems like a bit of lose to me, because what people
like about Pylons 1 tmpl_context is that they don't need to pass it
around and they can just jam crap on to it from anywhere. Needing to
both pass the request around as well as needing to write templates in
terms of a tmpl_context seems like the worst of both worlds to me
personally. What would the view return value mean in such a world? It
just seems like a lot of indirection to document, and it would also mean
forks of all the existing BFG templating systems.
- C
Madhu Alagu
Madhu Alagu
thanks
kk
Mike Orr
> On Sep 13, 11:49 am, Mike Orr <sluggos...@gmail.com> wrote:
>
>> Can it be made into a request method so you don't have to pass the
>> request object? That would be more OO.
>
> Yea, maybe request.link? request.url would conflict with the webob url
> property.
It's a good enough name for now. It does connote an entire <a> rather
than just the URL (cf. webhelpers.html.tags.link_to()). But I can't
think of a better name.
>
>> Or do you have to paste the markup text from the subprojects and
>> convert all "autoclass" to "class" by hand? The problem with this is
>> it would gradually drift out of date unless you went through every few
>> months looking for differences between your docs and the originals,
>> which would take a lot of time.
>
> Yea, we're going to have to compose copy/paste to an extent, from the
> other docs.
Well, hopefully '.. autoclass' will work if the package is installed.
WebHelpers and other packages uses '.. autoclass' extensively. It's
one thing to copy ReST documentation from another package. It's
another thing to reconstruct the ReST from the HTML or paste it
directly from the docstrings. which is what you'd have to do if
autoclass doesn't work.
--
Mike Orr <slugg...@gmail.com>
Mike Orr
> On Sun, 2010-09-19 at 18:36 -0700, Ben Bangert wrote:
>> Yea, we're going to have to compose copy/paste to an extent, from the
>> other docs.
>
> I've indicated to Ben that I am willing to genericize the BFG docs to
> some extent by not linking to internal stuff in API documentation
> needlessly. But I doubt this will really do much good; there are places
> where those kinds of links are just required. It will probably boil
> down to everything needing to be cutnpasted.
Most of the other Pylons dependencies are pretty solidified so they
shouldn't change much, and when they do it's some obscure feature
rather than the basic Pylons API. For BFG, we'll have to see how the
documentation comes out, how much of it refers to things that are
changing. As long as you're aware of which parts of the API the Pylons
docs cover, it should be pretty easy to remember, "This part affects
the Pylons docs." Especially as we'll be covering only a
Pylons-typical application, and referring directly to the BFG docs for
anything beyond that.
>> On a side-note, when using the "renderer=" approach to rendering a
>> template, the dict results go into the template global namespace....
>> should they instead go into tmpl_context?
>
> My $.02.. if you don't have a threadlocal tmpl_context around for
> people to jam values onto/into, it'd just confuse people if the dict
> values they returned from a view weren't passed as top-level names to
> the template, and instead were made available as the subkey
> "tmpl_context".
>
> - C
The best solution is a config flag. There's precedent for this in
``config['pylons.strict_tmpl_context']``. There's a conflict between
the Pylons tradition, where all variables passed to templates are
exposed under 'c', and the TurboGears tradition, where they're exposed
at the top level. We can't just throw the Pylons tradition under the
bus, especially because it would force people to rewrite their
templates for no obvious benefit. It could copy the variables to both
places by default, but have a flag to put them either at the top level
or under 'c'.
--
Mike Orr <slugg...@gmail.com>
Chris McDonough
The problem isn't the tool's ability to find the implementation and use
its existing documentation. That we have down pretty much cold, and it
will work just fine. The problems are instead:
- :ref: links buried inside docstrings of the existing
BFG implementation docstrings which point at BFG narrative
documentation. These will point off to nowhere when the same
documentation is rendered as part of the Pylons doctree.
- Ben wants to create a facade Pylons API for all (most?) BFG
APIs. Existing BFG implementation docstrings
have :class:, :function:, :method:, etc references buried inside
then, which, for Pylons will point to the wrong places (each
will point at the BFG dotted name instead of the Pylons dotted
name).
I am willing to remove "unnecessary" references from BFG docstrings to
help slightly here, but I don't think it will help much. I can't remove
them all: their existence is deliberate, to help people navigate the BFG
docs.
I think the best bet would be some sort of "facade generator" which not
only creates the Pylons facade module(s) for BFG functions, but which
also scrubs or modifies the docstrings of BFG APIs.
- C
Chris McDonough
> On Sun, Sep 19, 2010 at 7:01 PM, Chris McDonough <chr...@plope.com> wrote:
> > On Sun, 2010-09-19 at 18:36 -0700, Ben Bangert wrote:
> >> Yea, we're going to have to compose copy/paste to an extent, from the
> >> other docs.
> >
> > I've indicated to Ben that I am willing to genericize the BFG docs to
> > some extent by not linking to internal stuff in API documentation
> > needlessly. But I doubt this will really do much good; there are places
> > where those kinds of links are just required. It will probably boil
> > down to everything needing to be cutnpasted.
>
> Most of the other Pylons dependencies are pretty solidified so they
> shouldn't change much, and when they do it's some obscure feature
> rather than the basic Pylons API. For BFG, we'll have to see how the
> documentation comes out, how much of it refers to things that are
> changing. As long as you're aware of which parts of the API the Pylons
> docs cover, it should be pretty easy to remember, "This part affects
> the Pylons docs." Especially as we'll be covering only a
> Pylons-typical application, and referring directly to the BFG docs for
> anything beyond that.
AFAIK, Ben doesn't want to do that. He wants all the docs presented in
terms of Pylons, not punting to the BFG docs for anything at all.
- C
Mike Orr
BFG is bigger than all the other Pylons dependencies combined. We
can't have 30% of the Pylons manual referring to BFG features that
aren't normally used in Pylons apps, especially if Pylons has a more
specific way to enable it.
It sounds like we need a preprocessor to import documentation sources
and sanitize foreign cross-references. Can that be done as a Sphinx
plugin?
--
Mike Orr <slugg...@gmail.com>
Chris McDonough
> >
> > AFAIK, Ben doesn't want to do that. He wants all the docs presented in
> > terms of Pylons, not punting to the BFG docs for anything at all.
>
> BFG is bigger than all the other Pylons dependencies combined. We
> can't have 30% of the Pylons manual referring to BFG features that
> aren't normally used in Pylons apps, especially if Pylons has a more
> specific way to enable it.
I don't really know the subset of BFG APIs that Ben wants pointed at by
a Pylons facade. But whether it be 5% of BFG or 95%, that subset will
likely need its own documentation, so the problem really is the same.
> It sounds like we need a preprocessor to import documentation sources
> and sanitize foreign cross-references. Can that be done as a Sphinx
> plugin?
Nobody knows without spending the time.
- C
Ben Bangert
> BFG is bigger than all the other Pylons dependencies combined. We
> can't have 30% of the Pylons manual referring to BFG features that
> aren't normally used in Pylons apps, especially if Pylons has a more
> specific way to enable it.
Indeed, but after looking through the BFG docs, I'm having difficulty finding something that people might not need to reference. Chris had mentioned he planned on trimming quite a bit from the BFG docs as they are overly verbose (650 pages printed apparently!), so I think there's room to trim and be more concise. Pylons won't be documenting it quite the same either, the declarative way (using ZCML) will be relegated to a single chapter for those that want/need to use it.
> It sounds like we need a preprocessor to import documentation sources
> and sanitize foreign cross-references. Can that be done as a Sphinx
> plugin?
That sounds like it might be more effort than just copy/pasting the bits we need in, and ensuring their docs flow well with the rest of the Pylons docs.
- Ben
Chris McDonough
> On Sep 20, 2010, at 2:58 PM, Mike Orr wrote:
>
> > BFG is bigger than all the other Pylons dependencies combined. We
> > can't have 30% of the Pylons manual referring to BFG features that
> > aren't normally used in Pylons apps, especially if Pylons has a more
> > specific way to enable it.
>
> Indeed, but after looking through the BFG docs, I'm having difficulty finding something that people might not need to reference. Chris had mentioned he planned on trimming quite a bit from the BFG docs as they are overly verbose (650 pages printed apparently!), so I think there's room to trim and be more concise. Pylons won't be documenting it quite the same either, the declarative way (using ZCML) will be relegated to a single chapter for those that want/need to use it.
I will probably get rid of some stuff in the next book release, but it's
going to be at least 500 (printed) pages even trimmed. A lot of that is
narrative and tutorial content, which you probably either don't want or
you want to carve out and present in a Pylons-ish fashion. The API docs
without the rest of the stuff is about 100 pages.
- C
Mike Orr
How many full-time staff do you have available for two months? Just
converting the hundreds of references to plain text would take hours,
plus rewording the hundred-some pages of BFG docs and hundred-some
other docs and a few more for SQLAlchemy (or you want to put the
entire SQLAlchemy manual in too). The Encyclopedia of Pylons!
--
Mike Orr <slugg...@gmail.com>
Ben Bangert
> How many full-time staff do you have available for two months? Just
> converting the hundreds of references to plain text would take hours,
> plus rewording the hundred-some pages of BFG docs and hundred-some
> other docs and a few more for SQLAlchemy (or you want to put the
> entire SQLAlchemy manual in too). The Encyclopedia of Pylons!
I don't consider SQLAlchemy to be 'core' to Pylons, the core things are:
- Sessions
- Caching
- Request Object
- Response Object
- Configuration
- Dispatch
- Template Rendering
- Extensibility Points
I really hope it doesn't take hundreds of pages of text to cover those. Hundreds and hundreds of pages and full-time staff are what books are for. If someone feels like that, they should write a book. :)
Since many people use relational databases, we'll of course document how to write an app with it, like we do now.
Anyways, I'll give it a shot first, and we'll see how it goes.
Santhosh
I checked the new developing version of pylons .The new version is
entirely different from the older version . How can the developers
follow this ? .The developers compelled to have change the developed
software because if they remain in the older version there may be have
no support .
Please clear the doubts about this .
Thanks and Regards
Ben Bangert
> I checked the new developing version of pylons .The new version is
> entirely different from the older version . How can the developers
> follow this ? .The developers compelled to have change the developed
> software because if they remain in the older version there may be have
> no support .
I don't understand what you mean by "How can the developers follow this?". I posted the entire thread here to try and help any other developers follow it.
It's quite different, because the current Pylons 1.0 implementation is more or less "frozen", the implementation of most of it can't be changed since so much of it was directly subclassed by developers in their own apps. This style of customization was useful, but led to practical limitations on extensibility, and our own ability to move Pylons forward. Rather than re-inventing a bunch of code all over again, this new version went forward to build on other code to allow the new Pylons to be substantially more extensible, more efficient, and not have developers subclassing objects from Pylons (which limits our ability to make changes to the framework).
I don't see what the worry is about remaining on the older version, the Pylons book and the documentation is not going anywhere. The same level of documentation support is going to remain available for Pylons 1.0, as there is a large installed base that most likely isn't transitioning all that quickly. There is no book for the new Pylons paradigms yet, so you'll see a much higher level of 'support' in the way of blog postings, and documentation for 1.0 for some time to come I believe.
Cheers,
Ben
Chris McDonough
The trunk is also currently entirely bw compatible with Pylons 1.0. You
don't *need* to use the new features.
Madhu Alagu
Pylons 1.0:
def login(self):
response.content_type = 'application/vnd.mozilla.xul+xml'
login=st.load_form('login.kk')
return login
I would like to try in Pylons 2.0.The template source
(st.load_form('login.kk') ) load from the remote server.
thanks
kk
Chris McDonough
documentation which shows you to do this sort of thing "the new way".
In the meantime, the code you have below will also work on the trunk
without any changes, as far as I know.
Mike Orr
comments already worried that Pylons 2 is about to turn the world
upside down imminently. But my impression is there's still several
months worth of development. So maybe a beta by the end of the year
and the final sometime next winter or spring?
--
Mike Orr <slugg...@gmail.com>