Quantcast

plone.api – back to the future?

classic Classic list List threaded Threaded
62 messages Options
1234
Nejc Zupan Nejc Zupan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

On 27/02/2012, at 11:24, Martin Aspeli wrote:

On 27 February 2012 03:02, Nejc Zupan <[hidden email]> wrote:
Hi all,

as some of you have already noticed, work has begun on a new package:
plone.api.

I think this is really great :)

Thanks!

There is a risk that we'll end up in a situation where all of our own
packages depend on plone.api (I think this was Malthe's concern),
creating a somewhat challenging dependency management situation. We
need to think about how we address that, perhaps by mandating that
Plone core packages can't use plone.api, i.e. it's a "consumer-facing"
package only.

Absolutely. This package is meant for consumers, for integrators.
If you are a core developer, than you better know your shit and use the
underlying APIs and not the plone.api abstraction layer. I strongly discourage
any core code using plone.api because it's goal is to cover 20% of use
cases and core code needs to cover 100% of use cases (or close).


Another option would be to make plone.api have 'soft'
dependencies only i.e. the API functions are available if the relevant
packages are in sys.path, otherwise they give an error, but there is
no install_requires dependency for things like Products.CMFPlone.

We need Products.CMFPlone as an install_requires so that we get
an auto-generated API from method docstrings. Sphinx needs to import
all code in order to generate this: http://readthedocs.org/docs/ploneapi/en/latest/api.html


First off - these methods use lowercase_and_underscore() methods. That
is what PEP8 (now!) says, but it's not the Zope standard. Since you
can't replicate every function on every object, you can't hide all the
mixedCase() methods. Dexterity started out as the former and had a
painful transition to the latter as API code became really confusing.
I think we just need to accept mixedCase() and stick with it.

-1, but mostly on a personal preference level


get_tool() should be called getToolByName(). That one is already an
API and having two things importable from two places that do the same
thing with similar-but-different names is confusing. This is mainly
about old documentation and code that we can't expect to update in one
fell swoop.

-1
Old documentation and code will still work and can be kept that way.
For completely new developers (I'm hauling 10 new students into Plone 
this July!) it's just so much easier to remember get_tool(), especially
if it lists all possible tools in it's docs.


get_all() for users is likely to be impossible in many scenarios (e.g.
LDAP/AD) and very, very slow. Probably best not to expose this as an
API.

-1
We want to cover 20% of usecases. If you have AD with thousands of 
users, you better know your shit. Though we definitely should state it docs
the limitations of this method (as in, it will be slow if you have a lot of users)

A search-based API is better.

And can be similarly abused: api.user.search("*"), not solving anything.


We should consider the API on objects returned by items as well. At
the very least, dict-like access to folderish items (which works, even
for AT content), but also common methods like getId().

The dict-like access to folderish items is already documented.

And also why we don't want to use wrappers on returned objects:


I was hoping to see some content search/catalog APIs.

Definitely on the list of ideas, but we couldn't reach a consensus of how it should
behave. If we come up with a proposal that we mostly agree on, it goes in.


There is no API for for developing new functionality, e.g. registering
new views, viewlets etc. I'd suggest trying to incorporate those into
plone.api may be a fallacy, as they are well-established elsewhere.
However, the documentation should cover where these are and give some
examples of important constructs. At the very least, I'd cover views.

Again, there were a lot of discussions, but no consensus reached. Proposals
need further work, so we can all agree on them. 


We should either subsume or extend the plone_portal_state and
plone_context_state views for some of this. Access from TAL (including
expressions on things like actions) will be important. They also allow
for per-request caching which is important for performance. A simple
way to do that may be to replicate the relevant APIs on those views
and have the module-global function look up the view and call the
method.

I'm sorry but I cannot wrap my brain around this last paragraph. Can you
re-phrase please? 


Note that *no code* has been written so far. All focus went into getting
consensus on
what to include and how the API should look like. In this light:

Please don't go around adding/fixing API without first getting a few
"+1"s from
*non-rockstar* developers. It is absolutely crucial that whatever gets into
plone.api
to be understandable without years of Plone experience. I'm sure we missed
some
common use-cases, let's get them out there in the open to discuss whether to
include
them in plone.api.

I'll have a look through chapter 9 of PP4D and pull out anything I
felt was important enough to include there that may be missing.

Nice! Please add proposals as issues on GitHub.


We should also look at the Dexterity Developer Manual, which intends
to expose useful content operations, even if not exactly Dexterity
specific.

Same here, issues on GitHub.


Actual method implementations are very welcome, but we'd like the API to
stay mostly
frozen unless the majority agrees on changing it. Baby steps. Use branches
and
pull-requests, keep master clean.

Good ideas. I think writing the implementations will be relatively easy.

Yep, I agree. 


z.

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers

smime.p7s (2K) Download Attachment
Nejc Zupan Nejc Zupan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by yuri-2
On 27/02/2012, at 14:20, Yuri wrote:

> Shouldn't the software adhere to the apis, instead of the apis adhere to
> the software? :)

Yes, that is the idea.


z.
------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers

smime.p7s (2K) Download Attachment
Martin Aspeli Martin Aspeli
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Nejc Zupan
Hi,

On 27 February 2012 13:31, Nejc Zupan <[hidden email]> wrote:

> Another option would be to make plone.api have 'soft'
> dependencies only i.e. the API functions are available if the relevant
> packages are in sys.path, otherwise they give an error, but there is
> no install_requires dependency for things like Products.CMFPlone.
>
>
> We need Products.CMFPlone as an install_requires so that we get
> an auto-generated API from method docstrings. Sphinx needs to import
> all code in order to generate
> this: http://readthedocs.org/docs/ploneapi/en/latest/api.html

You can do that with an 'extra' for the purposes of generating the docs.

> First off - these methods use lowercase_and_underscore() methods. That
> is what PEP8 (now!) says, but it's not the Zope standard. Since you
> can't replicate every function on every object, you can't hide all the
> mixedCase() methods. Dexterity started out as the former and had a
> painful transition to the latter as API code became really confusing.
> I think we just need to accept mixedCase() and stick with it.
>
>
> -1, but mostly on a personal preference level

That's a bullshit reason. ;-)

Please don't make the same mistake that Dexterity did (and which was
painful to reverse). How on earth is a new developer supposed to
understand that imports from plone.api use one convention, but methods
on objects returned from its calls - and most other parts of Plone -
use another? PEP8 actually says existing convention takes priority
over fidelity to the PEP8 suggestions.

> get_tool() should be called getToolByName(). That one is already an
> API and having two things importable from two places that do the same
> thing with similar-but-different names is confusing. This is mainly
> about old documentation and code that we can't expect to update in one
> fell swoop.
>
>
> -1
> Old documentation and code will still work and can be kept that way.
> For completely new developers (I'm hauling 10 new students into Plone
> this July!) it's just so much easier to remember get_tool(), especially
> if it lists all possible tools in it's docs.

The point is that I may read some code like this:

portal_url = getToolByName(context, 'portal_url')

and then somewhere else, I may read:

portal_url = get_tool(context, 'portal_url')

The import statement is scrolled out of view, or not part of the
example. The overlap is confusing. And getToolByName is probably one
of the few 'API-like' functions we have today, an indirection instead
of doing aq_acqiure(context, 'portal_url') or whatever.

Your 10 new users will pretty soon move beyond the pristinely simple
API. We need to consider that they shouldn't drop off a cliff,
learning-curve-wise, when they do. We have a legacy codebase and some
kind of compromise in consideration of it will always be necessary.

> get_all() for users is likely to be impossible in many scenarios (e.g.
> LDAP/AD) and very, very slow. Probably best not to expose this as an
> API.
>
>
> -1
> We want to cover 20% of usecases. If you have AD with thousands of
> users, you better know your shit. Though we definitely should state it docs
> the limitations of this method (as in, it will be slow if you have a lot of
> users)

No, seriously. This is another one of those 'fall of a cliff' things.
As soon as your site scales, get_all() becomes one of those things
that makes it possible to DoS your site in seconds. People should not
be expected to know of this danger.

> A search-based API is better.
>
>
> And can be similarly abused: api.user.search("*"), not solving anything.

Yes, but here it is more obvious what you're doing. It's a question of
what you encourage people to do. With a get_all() people will call
that, loop over the results and apply their own filter. It can be
disastrous performance-wise, and will not work in all cases because
underlying user storage mechanisms don't allow it for the very same
reason.

If we're trying to make things simpler for people, we also need to
consider nudging them towards good implementation choices without them
having to be an expert on the various bottlenecks and problems in the
solution. Saying that the only way to get users in bulk is to search,
is on that scale.

> We should consider the API on objects returned by items as well. At
> the very least, dict-like access to folderish items (which works, even
> for AT content), but also common methods like getId().
>
>
> The dict-like access to folderish items is already documented.
> See http://readthedocs.org/docs/ploneapi/en/latest/content.html#get-content-example.

Great!

We also need to consider attribute/field value access, as David said.

> And also why we don't want to use wrappers on returned objects:
> http://readthedocs.org/docs/ploneapi/en/latest/rationale.html#faq

Completely agree. Wrappers are a huge headache.

> I was hoping to see some content search/catalog APIs.
>
>
> Definitely on the list of ideas, but we couldn't reach a consensus of how it
> should
> behave. If we come up with a proposal that we mostly agree on, it goes in.

I think the portal_catalog __call__() API is fine, but we should
shield people from having to get the portal_catalog tool (which has
all kinds of scary methods) just to get to the method. And we should
call it search(), not searchResults(), a retarded method name if ever
there was one. You pass a dict and get back a lazy list of brains.

We just need to document the common indexes and explain where in the
ZMI you look for other indexes. We also need to document brains and
metadata.

> There is no API for for developing new functionality, e.g. registering
> new views, viewlets etc. I'd suggest trying to incorporate those into
> plone.api may be a fallacy, as they are well-established elsewhere.
> However, the documentation should cover where these are and give some
> examples of important constructs. At the very least, I'd cover views.
>
>
> Again, there were a lot of discussions, but no consensus reached. Proposals
> need further work, so we can all agree on them.

Yep. Maybe best to keep separate for now anyway, as it's effectively a
different 'class' of API.

> We should either subsume or extend the plone_portal_state and
> plone_context_state views for some of this. Access from TAL (including
> expressions on things like actions) will be important. They also allow
> for per-request caching which is important for performance. A simple
> way to do that may be to replicate the relevant APIs on those views
> and have the module-global function look up the view and call the
> method.
>
>
> I'm sorry but I cannot wrap my brain around this last paragraph. Can you
> re-phrase please?

See Laurence's comment (in the other thread?), essentially. It needs
to be possible to call API methods from untrusted code/TAL/actions,
which means we want them to be accessible by traversing to a view. We
have some 'API' functions in plone.app.layout.globals, and we want to
make sure we have those in plone.api and have a way to get to the API
functions via a view lookup like
context/@@plone_portal_state/navigationRootUrl or whatever.

> Note that *no code* has been written so far. All focus went into getting

Martin

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Martin Aspeli Martin Aspeli
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Nejc Zupan
On 27 February 2012 13:11, Nejc Zupan <[hidden email]> wrote:

> On 27/02/2012, at 07:37, David Glick wrote:
>
> Some suggestions:
>
> 1. Regarding the calls like get_site_url() and get_request(), it's a bit
> misleading to say that these will *always* be available. It would be good to
> warn that the API is intended for use within code published by the
> ZPublisher (which sets up the necessary thread locals), as opposed to
> external methods or code run via bin/instance run or whatever.  Uh...I'll
> let you guys translate that into non-Zope-addled-brain language. :)
>
>
> Definitely. If someone can give me a definitive list of when get_request()
> and such won't work,
> and possibly links to in-depth explanations why, I'm happy to add this to
> the API documentation
> (as in plone.api
> limitations). See https://github.com/plone/plone.api/issues/1.

The basic idea is, if your code is:

 - within a view, viewlet or portlet
 - in a page template (TAL)
 - in a TTW "script (python)"
 - in a GenericSetup setup handler
 - in an External method (yes, David, they are published too...)
 - in a method on a content item (most likely)
 - ... anything else?

then your code is being executed as a result of the publisher finding
that resource based on the inbound path traversal and calling it. In
this case, you have traversed over the Plone site root at least, and
various threadlocals are set so that things like getRequest() from
zope.globalrequest, getSite() and context.REQUEST work. If you are
running a script through bin/instance debug or bin/instance run or in
a unit test, then no traversal has happened.

I think for most people, it's not going to be an issue except perhaps
in the unit test scenario.

> If not, please at least clarify in the documentation which API calls check
> permissions and which don't; this info is currently omitted.
>
>
> I'll need help here, someone going through the methods one by one and
> writing down what the
> security implications are. See https://github.com/plone/plone.api/issues/3.

The main thing to warn about are the methods that do explicit security
checks (or, we make the API not do that). They are:

 - invokeFactory()
 - portal_workflow.doActionFor()
 - manage_objectPaste

and possibly some others.

> 3. This is me channeling wiggy: For the user API, can we please use
> "user_id" as the argument name instead of "username"? "Username" and "user
> id" are slightly different concepts in PAS and it gets endlessly confusing
> when the terminology changes from place to place. (We should probably
> supporting getting a user either by user_id or login.)
>
>
> What the underlying terminology uses is not that relevant. The main question
> is How should the
> API look like. In an ideal world, disregarding what goes on underneath, do
> we want the
> api.user.create() to have:
>  - ``username`` and ``user`` parameters OR
>  -  ``userid`` and ``user`` parameters
>
> I vote the former. What do you think?

The point is that userid and username are separate concepts. One is a
unique id that never changes. The other is a name you use to log in
with and which may change over time. Various APIs expect one or the
other. In many cases, userid and username are the same, but then
sometimes they're not and your code breaks, which can happen in config
e.g. when moving to an integrated environment. It's important to be
clear about the distinction.

For this reason, I wouldn't say 'user' because it's (a) ambiguous and
(b) could refer to a user *object* rather than the user name or id
(which are strings).

Again, I appreciate this is irritating complexity, but it's complexity
that people will hit at the wrong time, blindly, unless we (a) nudge
them towards using the right approach (b) are consistent in our use of
terms and (c) provide helpful documentation, including "common
gotchas".

> Calls to:
>  a. get a content item's UID
>
>
> Should this just be documented or do we need an actual api helper method.
> Isn't is just content.UID()?

No, it's

from plone.uuid.interfaces import IUUID
uuid = IUUID(context)

The former is AT-specific. A convenience method would be useful.

>  c. grant or revoke a permission to a role within a particular context
>
>
> Cannot this be easily performed through UI. Does it fall in the 20% of most
> common tasks?

It's a fairly common thing to want to do, especially in
bootstrapping/setup code and tests. And, the underlying API is awkward
to use.

>  d. get the navigation root (which may be different than the site root)
>
>
> If you have a site where navigation root is different than site root, you
> are doing something funky
> and should know what you are doing without an abstraction layer covering it
> up for you.
> A use-case that plone.api does not want to cover.

I'm not sure I agree, though I agree it's less common. I think it's
very trivial to add both, though. More importantly, I think we should
promote 'navigation root' as the primary concept. Most people care
about "the home page", i.e. what users get to when they click the site
logo or on a 'home' link. That's always the nav root, but only
sometimes the site root. The site root can be hidden from view with
virtual hosting (config, not code!). For things like catalog searches
with a path filter or URL construction, navigation root is a better
concept.

>  f. format a date/time or number for the current locale
>
>
> Also good, see https://github.com/plone/plone.api/issues/8.

Maybe also string localisation?

>  g. make sure a given path exists (i.e. add several levels of folder
> structure with one call)
>
>
> Shall this be a separate method or a flag in create/move/copy?

I think you want a method to test, even if you also have a policy flag
on those methods.

>  h. activate, upgrade, or deactivate an add-on
>
>
> Uhm ... again, is it in the 20%? Isn't the UI approach good enogh and we
> document that
> rather than adding another method to plone.api (I really want to keep it
> sleek).

I think this is mainly done with GenericSetup or UI, so I'd agree with
keeping this out for now.

>  i. As Laurence and Andreas mentioned, the things currently included in the
> views in plone.app.layout.globals...this also requires some discussion of
> what parts of the API to make accessible to untrusted code (i.e. page
> templates and TALES expressions).
>
>
> If something in there proves usefull, we can easily add a method to
> plone.api that gets the relevant view
> and then the relevant method. Is there something in globals that is used all
> the time and we don't yet
> have in plone.api?

The main thing is that you want the API to be available from TAL. I'd
also just do a bit of a cross-check between plone_portal_state and
plone_context_state and plone.api.

Finally, another source of API-ish calls:
http://pypi.python.org/pypi/plone.app.testing/4.0.2#common-test-patterns

Martin

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Nejc Zupan Nejc Zupan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Martin Aspeli
On 27/02/2012, at 14:50, Martin Aspeli wrote:

On 27 February 2012 13:31, Nejc Zupan <[hidden email]> wrote:

Another option would be to make plone.api have 'soft'
dependencies only i.e. the API functions are available if the relevant
packages are in sys.path, otherwise they give an error, but there is
no install_requires dependency for things like Products.CMFPlone.


We need Products.CMFPlone as an install_requires so that we get
an auto-generated API from method docstrings. Sphinx needs to import
all code in order to generate
this: http://readthedocs.org/docs/ploneapi/en/latest/api.html

You can do that with an 'extra' for the purposes of generating the docs.

Would this approach also work on ReadTheDocs.org? We're somewhat
limit there in terms of controlling the build. If it works, I'm definitely +1.


First off - these methods use lowercase_and_underscore() methods. That
is what PEP8 (now!) says, but it's not the Zope standard. Since you
can't replicate every function on every object, you can't hide all the
mixedCase() methods. Dexterity started out as the former and had a
painful transition to the latter as API code became really confusing.
I think we just need to accept mixedCase() and stick with it.


-1, but mostly on a personal preference level

That's a bullshit reason. ;-)

True :)


PEP8 actually says existing convention takes priority over fidelity to the PEP8 suggestions.

Yep, and it also says "although this is also an opportunity to clean up
 someone else's mess". 


get_tool() should be called getToolByName(). That one is already an
API and having two things importable from two places that do the same
thing with similar-but-different names is confusing. This is mainly
about old documentation and code that we can't expect to update in one
fell swoop.


-1
Old documentation and code will still work and can be kept that way.
For completely new developers (I'm hauling 10 new students into Plone
this July!) it's just so much easier to remember get_tool(), especially
if it lists all possible tools in it's docs.

The point is that I may read some code like this:

portal_url = getToolByName(context, 'portal_url')

and then somewhere else, I may read:

portal_url = get_tool(context, 'portal_url')

Nope, you read the following (omit context):
portal_url = get_tool(tool='portal_url')


The import statement is scrolled out of view, or not part of the
example.

It should be. We had an openspace here in Munich and *no one* could
spell out the import statement for getToolByName from the top of 
their head. No one. People have to look it up all the time (not everyone
is using mr.igor).


The overlap is confusing. And getToolByName is probably one
of the few 'API-like' functions we have today, an indirection instead
of doing aq_acqiure(context, 'portal_url') or whatever.

Doesn't mean that it cannot be further simplified.


Your 10 new users will pretty soon move beyond the pristinely simple
API. We need to consider that they shouldn't drop off a cliff,
learning-curve-wise, when they do. We have a legacy codebase and some
kind of compromise in consideration of it will always be necessary.

Yes, this is true. 


get_all() for users is likely to be impossible in many scenarios (e.g.
LDAP/AD) and very, very slow. Probably best not to expose this as an
API.


-1
We want to cover 20% of usecases. If you have AD with thousands of
users, you better know your shit. Though we definitely should state it docs
the limitations of this method (as in, it will be slow if you have a lot of
users)

No, seriously. This is another one of those 'fall of a cliff' things.
As soon as your site scales, get_all() becomes one of those things
that makes it possible to DoS your site in seconds. People should not
be expected to know of this danger.

A proposal: only allow get_all() if the users and groups control panel
allows listing users (in other words: "many users?" is un-checked)?


A search-based API is better.


And can be similarly abused: api.user.search("*"), not solving anything.

Yes, but here it is more obvious what you're doing. It's a question of
what you encourage people to do. With a get_all() people will call
that, loop over the results and apply their own filter. It can be
disastrous performance-wise, and will not work in all cases because
underlying user storage mechanisms don't allow it for the very same
reason.

We can still leave methods that have performance implications in plone.api
but have big red banners next to them explaining what can go wrong if 
they abuse them.


If we're trying to make things simpler for people, we also need to
consider nudging them towards good implementation choices without them
having to be an expert on the various bottlenecks and problems in the
solution. Saying that the only way to get users in bulk is to search,
is on that scale.

That is a fair point. Having search only, and then adding an example of
how to use search to get all users (with implications of what that means, 
performance wise).


We should consider the API on objects returned by items as well. At
the very least, dict-like access to folderish items (which works, even
for AT content), but also common methods like getId().


The dict-like access to folderish items is already documented.
See http://readthedocs.org/docs/ploneapi/en/latest/content.html#get-content-example.

Great!

We also need to consider attribute/field value access, as David said.



I was hoping to see some content search/catalog APIs.


Definitely on the list of ideas, but we couldn't reach a consensus of how it
should
behave. If we come up with a proposal that we mostly agree on, it goes in.

I think the portal_catalog __call__() API is fine, but we should
shield people from having to get the portal_catalog tool (which has
all kinds of scary methods) just to get to the method. And we should
call it search(), not searchResults(), a retarded method name if ever
there was one. You pass a dict and get back a lazy list of brains.

Good points.


We just need to document the common indexes and explain where in the
ZMI you look for other indexes. We also need to document brains and
metadata.

True.


There is no API for for developing new functionality, e.g. registering
new views, viewlets etc. I'd suggest trying to incorporate those into
plone.api may be a fallacy, as they are well-established elsewhere.
However, the documentation should cover where these are and give some
examples of important constructs. At the very least, I'd cover views.


Again, there were a lot of discussions, but no consensus reached. Proposals
need further work, so we can all agree on them.

Yep. Maybe best to keep separate for now anyway, as it's effectively a
different 'class' of API.

Indeed, yes.


We should either subsume or extend the plone_portal_state and
plone_context_state views for some of this. Access from TAL (including
expressions on things like actions) will be important. They also allow
for per-request caching which is important for performance. A simple
way to do that may be to replicate the relevant APIs on those views
and have the module-global function look up the view and call the
method.


I'm sorry but I cannot wrap my brain around this last paragraph. Can you
re-phrase please?

See Laurence's comment (in the other thread?), essentially. It needs
to be possible to call API methods from untrusted code/TAL/actions,
which means we want them to be accessible by traversing to a view. We
have some 'API' functions in plone.app.layout.globals, and we want to
make sure we have those in plone.api and have a way to get to the API
functions via a view lookup like
context/@@plone_portal_state/navigationRootUrl or whatever.

Ah, got it now, thanks!


z.

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers

smime.p7s (2K) Download Attachment
Martin Aspeli Martin Aspeli
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

Hi,

Your lack-of-chevron-quoting is making this hard to read, but...

On 27 February 2012 14:07, Nejc Zupan <[hidden email]> wrote:

> You can do that with an 'extra' for the purposes of generating the docs.
>
>
> Would this approach also work on ReadTheDocs.org? We're somewhat
> limit there in terms of controlling the build. If it works, I'm definitely
> +1.

Try it ;-)

> A proposal: only allow get_all() if the users and groups control panel
> allows listing users (in other words: "many users?" is un-checked)?

APIs that change based on UI config is probably not great. I think we
should just have a search API, make it clear how to 'get all' using
it, and put a big warning on it. This is a case where making it a bit
'hard' to perform an operation is good. It makes it clear this isn't
the way Plone was intended to be used.

> That is a fair point. Having search only, and then adding an example of
> how to use search to get all users (with implications of what that means,
> performance wise).

Yeah, this feels more right to me.

Martin

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Nejc Zupan Nejc Zupan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Martin Aspeli
On 27/02/2012, at 15:05, Martin Aspeli wrote:

On 27 February 2012 13:11, Nejc Zupan <[hidden email]> wrote:
On 27/02/2012, at 07:37, David Glick wrote:

3. This is me channeling wiggy: For the user API, can we please use
"user_id" as the argument name instead of "username"? "Username" and "user
id" are slightly different concepts in PAS and it gets endlessly confusing
when the terminology changes from place to place. (We should probably
supporting getting a user either by user_id or login.)


What the underlying terminology uses is not that relevant. The main question
is How should the
API look like. In an ideal world, disregarding what goes on underneath, do
we want the
api.user.create() to have:
 - ``username`` and ``user`` parameters OR
 -  ``userid`` and ``user`` parameters

I vote the former. What do you think?

The point is that userid and username are separate concepts. One is a
unique id that never changes. The other is a name you use to log in
with and which may change over time. Various APIs expect one or the
other. In many cases, userid and username are the same, but then
sometimes they're not and your code breaks, which can happen in config
e.g. when moving to an integrated environment. It's important to be
clear about the distinction.

For this reason, I wouldn't say 'user' because it's (a) ambiguous and
(b) could refer to a user *object* rather than the user name or id
(which are strings).

'user' is always (in the context of plone.api) the object, same as 'group'
is always the object.
'username' is always a string, same as 'groupname' is always a string.


Let's pick good names and stick to them (in the context of plone.api).


Again, I appreciate this is irritating complexity, but it's complexity
that people will hit at the wrong time, blindly, unless we (a) nudge
them towards using the right approach (b) are consistent in our use of
terms and (c) provide helpful documentation, including "common
gotchas".

I agree. I want the plone.api narrative documentation to nudge people
in the right direction, always.


Calls to:
 a. get a content item's UID


Should this just be documented or do we need an actual api helper method.
Isn't is just content.UID()?

No, it's

from plone.uuid.interfaces import IUUID
uuid = IUUID(context)

The former is AT-specific. A convenience method would be useful.

Ah, I just learned something new. In this case I agree a convenience method


 c. grant or revoke a permission to a role within a particular context


Cannot this be easily performed through UI. Does it fall in the 20% of most
common tasks?

It's a fairly common thing to want to do, especially in
bootstrapping/setup code and tests. And, the underlying API is awkward
to use.



 d. get the navigation root (which may be different than the site root)


If you have a site where navigation root is different than site root, you
are doing something funky
and should know what you are doing without an abstraction layer covering it
up for you.
A use-case that plone.api does not want to cover.

I'm not sure I agree, though I agree it's less common. I think it's
very trivial to add both, though. More importantly, I think we should
promote 'navigation root' as the primary concept. Most people care
about "the home page", i.e. what users get to when they click the site
logo or on a 'home' link. That's always the nav root, but only
sometimes the site root. The site root can be hidden from view with
virtual hosting (config, not code!). For things like catalog searches
with a path filter or URL construction, navigation root is a better
concept.

So why just don't make api.get_site() return navigation root instead of site root?


 f. format a date/time or number for the current locale


Also good, see https://github.com/plone/plone.api/issues/8.

Maybe also string localisation?

Definitely, please add it to a comment on GitHub.


 g. make sure a given path exists (i.e. add several levels of folder
structure with one call)


Shall this be a separate method or a flag in create/move/copy?

I think you want a method to test, even if you also have a policy flag
on those methods.

So, if I understand correctly: have something like "check_if_exists(path)"
and a flag in create/move/copy? Seams reasonable to me.


 i. As Laurence and Andreas mentioned, the things currently included in the
views in plone.app.layout.globals...this also requires some discussion of
what parts of the API to make accessible to untrusted code (i.e. page
templates and TALES expressions).


If something in there proves usefull, we can easily add a method to
plone.api that gets the relevant view
and then the relevant method. Is there something in globals that is used all
the time and we don't yet
have in plone.api?

The main thing is that you want the API to be available from TAL. I'd
also just do a bit of a cross-check between plone_portal_state and
plone_context_state and plone.api.

Yep, I agree.



Tnx, it went completely under my radar.


z.

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers

smime.p7s (2K) Download Attachment
Nejc Zupan Nejc Zupan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Martin Aspeli
On 27/02/2012, at 15:12, Martin Aspeli wrote:

> Your lack-of-chevron-quoting is making this hard to read, but...

URL with how to do that? I'm willing to adhere to quoting policies, I just need
to know what they are. Pointers to how to wrangle Mail.app around them also
welcome :).


> On 27 February 2012 14:07, Nejc Zupan <[hidden email]> wrote:
>
>> You can do that with an 'extra' for the purposes of generating the docs.
>>
>> Would this approach also work on ReadTheDocs.org? We're somewhat
>> limit there in terms of controlling the build. If it works, I'm definitely
>> +1.
>
> Try it ;-)

Heh, setup.py is still more or less black magic for me, but I will :).


>> A proposal: only allow get_all() if the users and groups control panel
>> allows listing users (in other words: "many users?" is un-checked)?
>
> APIs that change based on UI config is probably not great. I think we
> should just have a search API, make it clear how to 'get all' using
> it, and put a big warning on it. This is a case where making it a bit
> 'hard' to perform an operation is good. It makes it clear this isn't
> the way Plone was intended to be used.

+1, I'll write it up and RFC it.


z.


------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers

smime.p7s (2K) Download Attachment
Martin Aspeli Martin Aspeli
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

On 27 February 2012 14:28, Nejc Zupan <[hidden email]> wrote:
> On 27/02/2012, at 15:12, Martin Aspeli wrote:
>
>> Your lack-of-chevron-quoting is making this hard to read, but...
>
> URL with how to do that? I'm willing to adhere to quoting policies, I just need
> to know what they are. Pointers to how to wrangle Mail.app around them also
> welcome :).

Not sure. Plain text email, maybe? I've seen it with others, too.

Martin

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Guido Stevens Guido Stevens
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Martin Aspeli
On 02/27/2012 03:05 PM, Martin Aspeli wrote:
> On 27 February 2012 13:11, Nejc Zupan <[hidden email]> wrote:
>>  d. get the navigation root (which may be different than the site root)
>>
>>
>> If you have a site where navigation root is different than site root, you
>> are doing something funky

Like running a multi-lingual site? I don't consider that to be an edge
case for Plone, certainly in Europe.

:*CU#
--
***   Guido A.J. Stevens        ***   tel: +31.43.3618933    ***
***   [hidden email]   ***   Postbus 619            ***
***   http://www.cosent.nl      ***   6200 AP  Maastricht    ***

            s h a r i n g    m a k e s    s e n s e

   RT @StKonrath: Facebook spies on phone users' smartphone text
   messages, report says http://t.co/yY1g5vNU

   http://twitter.com/GuidoStevens

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
J-C Brand J-C Brand
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Martin Aspeli
On Mon, 2012-02-27 at 13:50 +0000, Martin Aspeli wrote:
<snip>

> > First off - these methods use lowercase_and_underscore() methods. That
> > is what PEP8 (now!) says, but it's not the Zope standard. Since you
> > can't replicate every function on every object, you can't hide all the
> > mixedCase() methods. Dexterity started out as the former and had a
> > painful transition to the latter as API code became really confusing.
> > I think we just need to accept mixedCase() and stick with it.
> >
> >
> > -1, but mostly on a personal preference level
>
> That's a bullshit reason. ;-)
>
> Please don't make the same mistake that Dexterity did (and which was
> painful to reverse). How on earth is a new developer supposed to
> understand that imports from plone.api use one convention, but methods
> on objects returned from its calls - and most other parts of Plone -
> use another? PEP8 actually says existing convention takes priority
> over fidelity to the PEP8 suggestions.

Can you please elaborate on how and when you recognised that adhering to
PEP8 for Dexterity was a mistake and what the consequences were?

Thanks
J-C


------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Nejc Zupan Nejc Zupan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Guido Stevens
On 27/02/2012, at 17:15, Guido Stevens wrote:

> On 02/27/2012 03:05 PM, Martin Aspeli wrote:
>> On 27 February 2012 13:11, Nejc Zupan <[hidden email]> wrote:
>>> d. get the navigation root (which may be different than the site root)
>>>
>>>
>>> If you have a site where navigation root is different than site root, you
>>> are doing something funky
>
> Like running a multi-lingual site? I don't consider that to be an edge
> case for Plone, certainly in Europe.
Ah, yes, multi-lingual slipped under our radars too.


z.
------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers

smime.p7s (2K) Download Attachment
Sean Upton Sean Upton
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Nejc Zupan
On Mon, Feb 27, 2012 at 6:11 AM, Nejc Zupan <[hidden email]> wrote:
> If you have a site where navigation root is different than site root, you
> are doing something funky
> and should know what you are doing without an abstraction layer covering it
> up for you.
> A use-case that plone.api does not want to cover.

Allow be to be a bit blunt: this scares me.  This is not all that
strange.  We cannot have a simplified API that pleases everybody, but
on the other side of the coin, we cannot just fiat these design
decisions at whim.

* A lot of work in various Plone 3 releases went into removing all of
the hacks that product-developers had to go through to use alternate
navigation roots.  Much of Plone's internals for search, navigation,
etc use this idea.

* I maintain an add-on that uses this, quite a few others rely on this as well.

* IIRC, multi-lingual sites do (and will likely going forward) want to
take advantage of this.

Thinking aloud a bit more:

* Quoting Chris McDonough on the subject of API design:
"Unfortunately, when designing a framework, you get exactly one shot
at creating 'the right' API."  We ought to ponder ways to route around
this axiom.

* We need to proceed with great care and deliberation, and getting the
(nominally official sounding) API right (and stable) should take a
while (and live in beta for some good amount of time).

* You should be able to use a newer plone.api with a slightly older
(supported) Plone version, and the decision of what API package
version to use is an add-on developer or integrator's decision to
override the defaults of the KGS.  Some reasonable efforts towards
compatibility need to be made to allow developers to choose to use a
slightly newer (bleeding edge) API version in a recently released
Plone to allow for the API to evolve with a bit longer tether from the
core Plone version.

* Is the eventual intent for plone.api.* to be a namespace package?
Is this a good idea or a bad idea?  I really think that certain area
experts or people working repeatedly on certain types of problems
would be best to guide and maintain APIs in parts, not as one
monolithic whole (for example, I have interest in user/member related
APIs as I keep building simplified adapters for this area on top of
PAS and the stock tools for my own use, and I would be interested in
collaborating with others interested in creating a better API for just
this problem only).

* If plone.api is a grassroots effort, I think the FWT needs to
provide (and solicit from developers here and on product-developers
list) steering, input, and design critique, review periodically (at
least a few rounds of review every few months before any API is ever
to be treated as initially stable)?

* There needs to be infrastructure for discussion and code-review
about each interfaces and each method, or some convention for using
our existing tools (github, trac, etc) to facilitate discussion about
the things in question (IMHO, mailing lists are too coarse-grained to
dabble in the minutiae of specific method signatures, etc).  With the
right tools, the community can design an API by merit, not by
happenstance.


Sean


[1] http://plope.com/pyramid_auth_design_api_postmortem

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Sean Upton Sean Upton
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by J-C Brand
On Mon, Feb 27, 2012 at 9:49 AM, Jan-Carel Brand <[hidden email]> wrote:

> On Mon, 2012-02-27 at 13:50 +0000, Martin Aspeli wrote:
> <snip>
>
>> > First off - these methods use lowercase_and_underscore() methods. That
>> > is what PEP8 (now!) says, but it's not the Zope standard. Since you
>> > can't replicate every function on every object, you can't hide all the
>> > mixedCase() methods. Dexterity started out as the former and had a
>> > painful transition to the latter as API code became really confusing.
>> > I think we just need to accept mixedCase() and stick with it.
>> >
>> >
>> > -1, but mostly on a personal preference level
>>
>> That's a bullshit reason. ;-)
>>
>> Please don't make the same mistake that Dexterity did (and which was
>> painful to reverse). How on earth is a new developer supposed to
>> understand that imports from plone.api use one convention, but methods
>> on objects returned from its calls - and most other parts of Plone -
>> use another? PEP8 actually says existing convention takes priority
>> over fidelity to the PEP8 suggestions.
>
> Can you please elaborate on how and when you recognised that adhering to
> PEP8 for Dexterity was a mistake and what the consequences were?

I would be interested in understanding the impacts of this as well.  I
like consistency, but I also prefer and use LCUS style for method and
identifier names exclusively in my own code.  I see the merits to
both, but I may be blind to the downsides.

The "cultural" argument:

There is an indirect "feeling" about the tenor and personality of an
API -- I cannot explain why, but from an "API" standpoint, LCUS
(preferably with as few underscores) makes for APIs that look more
friendly and less daunting.  Dunno, maybe it just looks less like
Java; maybe it just seems more humble.  Maybe it forces you to write
more resource-centric code to avoid ugly underscores (e.g. make
abstractions look like mappings instead of controllers of some other
resource's state -- see the way PAS deals with groups for an example).
 As ugly as underscore word delimiters are, they are less ugly than
mixed-case?

I would guess that there are cultural pre-dispositions among the
target audience of a simplified API (including Python devs outside of
Plone/Zope pedigree) that would find LCUS identifier style more
natural to find friendly.

Sean

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Fulvio Casali Fulvio Casali
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

On Mon, Feb 27, 2012 at 6:30 PM, Sean Upton <[hidden email]> wrote:
>
>
>
> I would be interested in understanding the impacts of this as well.  I
> like consistency, but I also prefer and use LCUS style for method and
> identifier names exclusively in my own code.  I see the merits to
> both, but I may be blind to the downsides.
>

LCUS = ?

Google is failing me here, sorry.

Thanks,
fulv

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Martin Aspeli-3 Martin Aspeli-3
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by J-C Brand


On 27 Feb 2012, at 16:49, Jan-Carel Brand <[hidden email]> wrote:

> On Mon, 2012-02-27 at 13:50 +0000, Martin Aspeli wrote:
> <snip>
>
>>> First off - these methods use lowercase_and_underscore() methods. That
>>> is what PEP8 (now!) says, but it's not the Zope standard. Since you
>>> can't replicate every function on every object, you can't hide all the
>>> mixedCase() methods. Dexterity started out as the former and had a
>>> painful transition to the latter as API code became really confusing.
>>> I think we just need to accept mixedCase() and stick with it.
>>>
>>>
>>> -1, but mostly on a personal preference level
>>
>> That's a bullshit reason. ;-)
>>
>> Please don't make the same mistake that Dexterity did (and which was
>> painful to reverse). How on earth is a new developer supposed to
>> understand that imports from plone.api use one convention, but methods
>> on objects returned from its calls - and most other parts of Plone -
>> use another? PEP8 actually says existing convention takes priority
>> over fidelity to the PEP8 suggestions.
>
> Can you please elaborate on how and when you recognised that adhering to
> PEP8 for Dexterity was a mistake and what the consequences were?

Not PEP8, just the lowercase/underscore convention for functions. It's a mistake in a Zope context because the Zope standard is mixedCase (it predates PEP8 making a recommendation on this) and this leads to confused code.

I feel quite strongly about this. Consistency is important. See above for why.

We discovered prior to 1.0 betas because all the docs were confused and code using Dexterity was a hodge podge of the two styles. Fixing it (and breaking early adopter code) was a blocker for making Dexterity more public. Had we had more than three or four users at that point, it would have been impossible to go back.

Martin
------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Martin Aspeli-3 Martin Aspeli-3
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Sean Upton


On 27 Feb 2012, at 17:06, Sean Upton <[hidden email]> wrote:

> On Mon, Feb 27, 2012 at 6:11 AM, Nejc Zupan <[hidden email]> wrote:
>> If you have a site where navigation root is different than site root, you
>> are doing something funky
>> and should know what you are doing without an abstraction layer covering it
>> up for you.
>> A use-case that plone.api does not want to cover.
>
> Allow be to be a bit blunt: this scares me.  This is not all that
> strange.  We cannot have a simplified API that pleases everybody, but
> on the other side of the coin, we cannot just fiat these design
> decisions at whim.
>
> * A lot of work in various Plone 3 releases went into removing all of
> the hacks that product-developers had to go through to use alternate
> navigation roots.  Much of Plone's internals for search, navigation,
> etc use this idea.
>
> * I maintain an add-on that uses this, quite a few others rely on this as well.
>
> * IIRC, multi-lingual sites do (and will likely going forward) want to
> take advantage of this.
>
> Thinking aloud a bit more:
>
> * Quoting Chris McDonough on the subject of API design:
> "Unfortunately, when designing a framework, you get exactly one shot
> at creating 'the right' API."  We ought to ponder ways to route around
> this axiom.
>
> * We need to proceed with great care and deliberation, and getting the
> (nominally official sounding) API right (and stable) should take a
> while (and live in beta for some good amount of time).
>
> * You should be able to use a newer plone.api with a slightly older
> (supported) Plone version, and the decision of what API package
> version to use is an add-on developer or integrator's decision to
> override the defaults of the KGS.  Some reasonable efforts towards
> compatibility need to be made to allow developers to choose to use a
> slightly newer (bleeding edge) API version in a recently released
> Plone to allow for the API to evolve with a bit longer tether from the
> core Plone version.
>
> * Is the eventual intent for plone.api.* to be a namespace package?
> Is this a good idea or a bad idea?  I really think that certain area
> experts or people working repeatedly on certain types of problems
> would be best to guide and maintain APIs in parts, not as one
> monolithic whole (for example, I have interest in user/member related
> APIs as I keep building simplified adapters for this area on top of
> PAS and the stock tools for my own use, and I would be interested in
> collaborating with others interested in creating a better API for just
> this problem only).
>

I'd favour a namespace package with extremely tight (FWT) control over who can use the namespace and for what.


> * If plone.api is a grassroots effort, I think the FWT needs to
> provide (and solicit from developers here and on product-developers
> list) steering, input, and design critique, review periodically (at
> least a few rounds of review every few months before any API is ever
> to be treated as initially stable)?
>

Agreed,

> * There needs to be infrastructure for discussion and code-review
> about each interfaces and each method, or some convention for using
> our existing tools (github, trac, etc) to facilitate discussion about
> the things in question (IMHO, mailing lists are too coarse-grained to
> dabble in the minutiae of specific method signatures, etc).  With the
> right tools, the community can design an API by merit, not by
> happenstance.

Substantial alpha periods may help this.

Martin
------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
Martin Aspeli Martin Aspeli
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Sean Upton
On 27 February 2012 17:30, Sean Upton <[hidden email]> wrote:

>> Can you please elaborate on how and when you recognised that adhering to
>> PEP8 for Dexterity was a mistake and what the consequences were?
>
> I would be interested in understanding the impacts of this as well.  I
> like consistency, but I also prefer and use LCUS style for method and
> identifier names exclusively in my own code.  I see the merits to
> both, but I may be blind to the downsides.
>
> The "cultural" argument:
>
> There is an indirect "feeling" about the tenor and personality of an
> API -- I cannot explain why, but from an "API" standpoint, LCUS
> (preferably with as few underscores) makes for APIs that look more
> friendly and less daunting.  Dunno, maybe it just looks less like
> Java;

I f-ing *hate* this argument. It crops up more than once in Python
circles. It's the kind of snobbery that makes open source developers
sound spoilt and petty.

(I realise I'm shooting the messenger here - sorry Sean)

> maybe it just seems more humble.  Maybe it forces you to write
> more resource-centric code to avoid ugly underscores (e.g. make
> abstractions look like mappings instead of controllers of some other
> resource's state -- see the way PAS deals with groups for an example).
>  As ugly as underscore word delimiters are, they are less ugly than
> mixed-case?
>
> I would guess that there are cultural pre-dispositions among the
> target audience of a simplified API (including Python devs outside of
> Plone/Zope pedigree) that would find LCUS identifier style more
> natural to find friendly.

The boat sailed a long time ago on this for Zope. Seriously. We have a
consistency problem already, but this would make it ten times worse.

For example:

import plone.api
import plone.api.content

catalog = get_tool(name='portal_catalog')

for item in catalog.searchResults(portal_type='News Item'):
    obj = item.getObject()
    plone.api.show_message("Found object %s" % obj.getId())

request = plone.api.get_request()
path = request['path']

obj = plone.api.content.get(path=path)
obj.setTitle("New title")

Okay, fairly non-sensical code, but the point here is that we have API
functions written in one style that return objects that use another
for their methods. To people learning Plone, this is a big deal. It
means you have to rely on rote learning to figure out what style to
use. Only once you've memorised the APIs (or figured out some kind of
obtuse heuristic based on the historical context of each class and
module) do you have a chance of guessing right most of the time.

We're not going to change the API of existing Zope and Plone
functions. Zope has had an explicit mixedCase policy for a long time,
which largely (but, sadly, not always) Plone has followed. Breaking
that now under the banner of trying to make things 'easier' for people
not familiar with Plone is just dumb.

Martin

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
JonStahl JonStahl
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

On Mon, Feb 27, 2012 at 12:18 PM, Martin Aspeli
<[hidden email]> wrote:

> We're not going to change the API of existing Zope and Plone
> functions. Zope has had an explicit mixedCase policy for a long time,
> which largely (but, sadly, not always) Plone has followed. Breaking
> that now under the banner of trying to make things 'easier' for people
> not familiar with Plone is just dumb.

I usually don't weigh in on technical issues like this, but, FWIW, I
think that Martin's arguments are spot-on.  Internal consistency is
really important.

US$0.02,
jon

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
David Glick (GW) David Glick (GW)
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: plone.api

In reply to this post by Martin Aspeli

On Feb 27, 2012, at 12:18 PM, Martin Aspeli wrote:

> On 27 February 2012 17:30, Sean Upton <[hidden email]> wrote:
>
>>> Can you please elaborate on how and when you recognised that adhering to
>>> PEP8 for Dexterity was a mistake and what the consequences were?
>>
>> I would be interested in understanding the impacts of this as well.  I
>> like consistency, but I also prefer and use LCUS style for method and
>> identifier names exclusively in my own code.  I see the merits to
>> both, but I may be blind to the downsides.
>>
>> The "cultural" argument:
>>
>> There is an indirect "feeling" about the tenor and personality of an
>> API -- I cannot explain why, but from an "API" standpoint, LCUS
>> (preferably with as few underscores) makes for APIs that look more
>> friendly and less daunting.  Dunno, maybe it just looks less like
>> Java;
>
> I f-ing *hate* this argument. It crops up more than once in Python
> circles. It's the kind of snobbery that makes open source developers
> sound spoilt and petty.
>
> (I realise I'm shooting the messenger here - sorry Sean)
>
>> maybe it just seems more humble.  Maybe it forces you to write
>> more resource-centric code to avoid ugly underscores (e.g. make
>> abstractions look like mappings instead of controllers of some other
>> resource's state -- see the way PAS deals with groups for an example).
>>  As ugly as underscore word delimiters are, they are less ugly than
>> mixed-case?
>>
>> I would guess that there are cultural pre-dispositions among the
>> target audience of a simplified API (including Python devs outside of
>> Plone/Zope pedigree) that would find LCUS identifier style more
>> natural to find friendly.
>
> The boat sailed a long time ago on this for Zope. Seriously. We have a
> consistency problem already, but this would make it ten times worse.
>
> For example:
>
> import plone.api
> import plone.api.content
>
> catalog = get_tool(name='portal_catalog')
>
> for item in catalog.searchResults(portal_type='News Item'):
>    obj = item.getObject()
>    plone.api.show_message("Found object %s" % obj.getId())
>
> request = plone.api.get_request()
> path = request['path']
>
> obj = plone.api.content.get(path=path)
> obj.setTitle("New title")
>
> Okay, fairly non-sensical code, but the point here is that we have API
> functions written in one style that return objects that use another
> for their methods. To people learning Plone, this is a big deal. It
> means you have to rely on rote learning to figure out what style to
> use. Only once you've memorised the APIs (or figured out some kind of
> obtuse heuristic based on the historical context of each class and
> module) do you have a chance of guessing right most of the time.
>
> We're not going to change the API of existing Zope and Plone
> functions. Zope has had an explicit mixedCase policy for a long time,
> which largely (but, sadly, not always) Plone has followed. Breaking
> that now under the banner of trying to make things 'easier' for people
> not familiar with Plone is just dumb.
>
> Martin


For the record, I also hate Zope and Plone's use of camel case. I'd like to find a way to move away from it in the long term, and I think plone.api is probably one of our best opportunities to set foot in the right direction.

Any argument for following the patterns of Zope/Plone API for the sake of consistency makes me laugh. Consistency? We ain't got none to follow.

That said, the topic feels like a silly one to spend a lot of community energy on, so this will be my last post on the matter. In the end what matters is that the APIs created are simple and *documented*, not how the words are separated in the names.

David



----------
David Glick
 Web Developer
 [hidden email]
 206.286.1235x32

The Engagement Party 2012. So much more fun than the wedding reception.

http://www.npoengagementparty.com



------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2
_______________________________________________
Plone-developers mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-developers
1234
Loading...