Re: Pyramid project templates
On Nov 23, 9:48 pm, Ben Bangert wrote: > On Nov 23, 2010, at 5:30 PM, Mike Orr wrote: > > > It sounds good in general. Will it still have a default index view > > with a welcome page? I think that's a good minimum to get people > > started. It saves user frustration and questions on the list, "How do > > I structure my views and make the first route? What should the page > > template look like?" > > I'm wary of putting that in, cause I would hope that people will create > projects more than just the first time ever. And having to constantly delete > all that stuff is annoying. I should hope that following the documentation > would answer those questions, as expecting users to derive knowledge about > how to write views and routes based purely off a single example seems just as > error-prone. People have to read documentation, there's no amount of hand > holding the code can do that will help a user who refuses to read any docs at > all. > My 0.02 cents on this. >From many bad nights of chasing bugs with TurboGears' quickstart command. Make it as simple as possible! In TG it was decided to go the "Full project route" and then having experience users delete what's not needed. Back then and still now I think that's a bad idea because a) most users will never delete anything for fear of breaking something b) most updates are painful because you need to diff the old project with a newly "quickstarted project" which gives a lot of false positives as you need to name your new temp package something different (otherwise paster will complain) c) it's a maintenance nightmare because you end up having stuff like if sqlalquemy this else that, because if two subpackages need to write to the same file it will get messy with paster. d) overall you end up having to know every possible combination which well does not scale at all. So in short make it as small as possible seriously! As for the "full option" I suggest a package to be created say pyramid- example which will contain a basic project for people that will want to "get started" you will clone/export that and build from there, this will give the "full setup experience" for people that want to strip down things from a working hello world. This package should be updated to the lastest quickstart before each release, and it's diff could even be the base for the migration document. As you will know exactly what changed from version to version given the magic of VCS :) > Yep, definitely. There is a need for a template that has a pylons-esque > setup, and I think that prolly should be its own package with its own docs. > Having it all in Pyramid is just too confusing, and makes the documentation > appear very wishy-washy. > > > So traversal doesn't need any boilerplate code? > perhaps a separate package with several different templates, something like http://pypi.python.org/pypi/ZopeSkel IMO should be the best. And then ALL documentation will be based on the main minimal package, and the section specific documentation could go something like. if you want a quickstart project with sqlalchemy you should do or install the PyramidSkel package and run paster -t pyramid_alchemy my_sqlalquemy_project This will even help with people getting to know what each part of the quickstart does instead of just assuming "it's all vital things for the app" Last but not least I'll like to point out that I really think we should carry over pylons way of building a basic controller so we could carry on the approach of building a project in steps rather than one chunk at the start. That's something I always liked and miss from TG. -- You received this message because you are subscribed to the Google Groups "pylons-devel" group. To post to this group, send email to pylons-de...@googlegroups.com. To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en.
Re: URL dispatch vs traversal
On Nov 24, 2:41 am, Mike Orr wrote:
> On Tue, Nov 23, 2010 at 8:21 PM, Mike Orr wrote:
> > On Tue, Nov 23, 2010 at 8:00 PM, Chris McDonough wrote:
> >> On Tue, 2010-11-23 at 19:35 -0800, Mike Orr wrote:
> >>> I wonder if it would be clearer to to put the URL Dispatch chapter
> >>> before Context Finding and Traversal in the manual.
>
> >> I sympathize with this, and I think we can probably organize it better.
> >> Casey Duncan is currently working on editing the book as a for-pay sort
> >> of thing. I'm hoping he'll come up with some concrete suggestions as to
> >> how to reorganize things, but maybe I can put a bug in his ear along the
> >> lines of your suggestion.
>
> >> FTR, it would be more technically accurate to say that users *will* be
> >> using a root object, a context object, and context finding when he uses
> >> URL dispatch, but he can mostly ignore their existence. URL dispatch
> >> literally is a context finding mechanism. This is why the docs are
> >> organized as they are now.
>
> >> OTOH, users do indeed need to know about view lookup even if they only
> >> use URL dispatch. A matched route doesn't always imply the lookup of
> >> one single canonical view. For example, if a route matches, it might go
> >> to one view if the request method is POST, another if the request method
> >> is GET.
>
> > OK, I think we can handle this in a short paragraph at the beginning
> > of the URL Dispatch chapter. Just quickly explain in passing what
> > these are and that the'll be covered more in depth in the following
> > chapters.
>
> Ignore this, I misunderstood your message. You said the user could
> remain blissfully unaware of these until they're ready to use them.
>
> How about an outline like this, roughly.
>
> CONTEXT FINDING AND VIEW LOOKUP
> --
> This section is about how Pyramid maps a user request (the URL plus
> certain other info included in the request) to a *view callable*. A
> view callable is a piece of code that takes a request and produces a
> response, such as an HTML page or a multimedia object. In Pyramid, the
> request and response are instances of Request and Response classes.
> Most Pyramid applications have several view callables, each one
> corresponding to a different kind of URL. View callables can also be
> grouped into *handlers*, where the handler is a class and the view
> callables are methods in that class.
>
> Pyramid provides two different ways to map a URL to a view callable.
> One is called URL Dispatch, familiar to Pylons and Routes users. It
> matches the entire URL against a set of rules known as *routes*, and
> the first matching route specifies which view callable to invoke. The
> other way is called Traversal, which is familiar to BFG, TurboGears,
> and Zope users. Traversal matches each URL component against keys of a
> dict-like root object, recursively mapping components to keys until a
> view callable is identified. An application can use one way, the other
> way, or both in different situations. The next chapter explains URL
> Dispatch; the following chapter covers Traversal. The N+3 chapter
> discusses hybrid applications using both URL Dispatch and Traversal.
> The N+4 chapter explains view callables in detail.
>
> [Move "What good is a context finding subsystem" and "Should I use
> traversal or URL dispatch" to traversal chapter.]
>
> URL DISPATCH
> ---
> Simple example mentioning 'add_route' and 'add_handler' (for both URL
> dispatch and traversal readers, so they recognize the methods when
> they see them)
>
> Traversal readers can now skip to the next chapter
>
> API, basic, and advanced usages
>
> It may be helpful to introduce a minimal view callable and handler, so
> that people can get a concrete feel for how the routing and view
> callables interact.
>
> Mention that a *context* exists, and explain it in URL Dispatch terms.
> The context contains additional information about the user's
> environment not included in the request. The context is mainly useful
> with Traversal, Normally all URL Dispatch requests use the same
> default context, but if you're using auth you may have to explicity
> specify a context; see the Auth chapter for details.
>
> TRAVERSAL AND HYBRID USAGE
> ---
>
> Start with a concise, concrete example, something as easy to grasp as
> a CherryPy root. Mention the characteristic methods: 'add_view'.
> ('add_model'?)
>
> Explain that Traversal is most useful when the URL refers to an
> arbitrary hierachical structure such as an object database (ZODB).
> [This replaces the "Should I use Traversal or URL Dispatch" section,
> but can be much shorter.]
>
> Shorten the Unix conceptual example. Don't get into shell commands and
> what the "inexperienced user" doesn't know. Just show a directory tree
> (the complete tree), and imagine cd'ing into each directory and
> looking for the next component. .__getitem__ is too abst
Re: pyramid terminology: "model"->"resource"
+0 from my part On Dec 15, 1:13 pm, Chris McDonough wrote: > I'm considering making a fairly major terminology change to the Pyramid > docs. I'd like to consider renaming the term "model" to "resource" in > the docs. > > Since repoze.bfg 0.1, we've used the term "model" to refer to each > object that forms the graph used by traversal. This is due to Pyramid's > Zope heritage: in a "Zopey" Pyramid app, these objects are indeed > persistent "domain model" objects, as they are nodes in a ZODB. > Seehttp://docs.pylonshq.com/pyramid/dev/designdefense.html#pyramid-uses-... > > But Pyramid doesn't actually have an opinion about whether the objects > used for traversal are "domain model" objects. Pyramid applications can > be constructed that have a traversal graph which represents only a > "sitemap" or a "security graph"; the objects in such a graph aren't > necessarily "domain models". In such an application, the domain model > may live entirely outside the graph of objects used for traversal. It > would be useful to have another term for objects in the traversal object > graph. > > Why "resource"? Well, a URL is a "universal resource locator", and > traversal could indeed be used to locate a resource in this sense. It's > not a 100% correct mapping of terminology, because an HTTP resource is > the body of the HTTP response, and this is usually computed by a view. > But it's closer than "model". > > API side effects of such a renaming: > > pyramid.url.model_url -> pyramid.url.resource_url > "resource specification" -> "package asset specification" > > ... and perhaps a few other minor changes. Obviously we'll leave > backward compat shims for all changed APIs around so we don't break > existing code. > > Does anyone strongly agree or strongly disagree with this? > > - C -- You received this message because you are subscribed to the Google Groups "pylons-devel" group. To post to this group, send email to pylons-de...@googlegroups.com. To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en.
