date:20210312

Re: [pylons-discuss] generating docs for views

2021-03-12 Thread 'Jonathan Vanasco' via pylons-discuss

Yes, it is much closer to your pyramid_openapi3 demos.  I'm not sure that 
project is a good candidate for my requirements or bandwidth, but I will 
dig into it - thanks!




On Friday, March 12, 2021 at 4:52:45 PM UTC-5 Steve Piercy wrote:

> My first thought was to use docstrings and Sphinx, but I don't think 
> that's what you want.
>
> It sounds like you want to document an API, something like 
> pyramid_openapi3.
>
> https://github.com/Pylons/pyramid_openapi3/
>
> RealWorld.io app API Demo (it might take a while to start up the app, as 
> it is on-demand only).
>
> https://pyramid-realworld.herokuapp.com/api
>
> --steve
>
>
> On 3/12/21 1:36 PM, 'Jonathan Vanasco' via pylons-discuss wrote:
> > I had a small Pyramid project which has grown into a much larger one.
> > 
> > Many Views service multiple Routes (multiple calls to `@view_config()`), 
> typically offering a default HTML version on a "bare" url, and a JSON 
> version with a ".json" suffix to the url.
> > 
> > Documenting these routes has become increasingly burdensome, and I 
> really need to simplify it.  For clarity, the docs are served by the 
> application itself and in a structured format.
> > 
> > Right now I have two types of documentation, and I'd like to consolidate 
> it into a single one.
> > 
> > * The original documentation was built off a Python file, 
> `/lib/docs.py`, which just notes the routes which have JSON endpoints, 
> gives an "about" docstring, and offers a dict about how the route functions 
> (GET vs POST, is it self-documenting, etc).
> > 
> > * As the project progressed, the routes started self-documenting.  Forms 
> were moved to POST only, with GET offering structured details 
> (instructions, required vs optional form elements, etc). Most of this is 
> defined by just returning a dict on GET operations.
> > 
> > I've been trying to figure out the best ways to consolidate this. 
> Perhaps using a custom decorator to declare and track this information into 
> a namespace?
> > 
> > Has anyone else worked on a scenario like this?  How did you handle it?
> > 
> > -- 
> > You received this message because you are subscribed to the Google 
> Groups "pylons-discuss" group.
> > To unsubscribe from this group and stop receiving emails from it, send 
> an email to pylons-discus...@googlegroups.com  pylons-discus...@googlegroups.com>.
> > To view this discussion on the web visit 
> https://groups.google.com/d/msgid/pylons-discuss/2cc3c09f-037a-4cf0-9a18-b464540a2305n%40googlegroups.com
>  
> <
> https://groups.google.com/d/msgid/pylons-discuss/2cc3c09f-037a-4cf0-9a18-b464540a2305n%40googlegroups.com?utm_medium=email_source=footer
> >.
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"pylons-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to pylons-discuss+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/pylons-discuss/b2946103-6911-48d7-b352-b75911b96d9dn%40googlegroups.com.

Re: [pylons-discuss] generating docs for views

2021-03-12 Thread Steve Piercy

My first thought was to use docstrings and Sphinx, but I don't think that's 
what you want.

It sounds like you want to document an API, something like pyramid_openapi3.

https://github.com/Pylons/pyramid_openapi3/

RealWorld.io app API Demo (it might take a while to start up the app, as it is 
on-demand only).

https://pyramid-realworld.herokuapp.com/api

--steve


On 3/12/21 1:36 PM, 'Jonathan Vanasco' via pylons-discuss wrote:
> I had a small Pyramid project which has grown into a much larger one.
> 
> Many Views service multiple Routes (multiple calls to `@view_config()`), 
> typically offering a default HTML version on a "bare" url, and a JSON version 
> with a ".json" suffix to the url.
> 
> Documenting these routes has become increasingly burdensome, and I really 
> need to simplify it.  For clarity, the docs are served by the application 
> itself and in a structured format.
> 
> Right now I have two types of documentation, and I'd like to consolidate it 
> into a single one.
> 
> * The original documentation was built off a Python file, `/lib/docs.py`, 
> which just notes the routes which have JSON endpoints, gives an "about" 
> docstring, and offers a dict about how the route functions (GET vs POST, is 
> it self-documenting, etc).
> 
> * As the project progressed, the routes started self-documenting.  Forms were 
> moved to POST only, with GET offering structured details (instructions, 
> required vs optional form elements, etc). Most of this is defined by just 
> returning a dict on GET operations.
> 
> I've been trying to figure out the best ways to consolidate this. Perhaps 
> using a custom decorator to declare and track this information into a 
> namespace?
> 
> Has anyone else worked on a scenario like this?  How did you handle it?
> 
> -- 
> You received this message because you are subscribed to the Google Groups 
> "pylons-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to pylons-discuss+unsubscr...@googlegroups.com 
> .
> To view this discussion on the web visit 
> https://groups.google.com/d/msgid/pylons-discuss/2cc3c09f-037a-4cf0-9a18-b464540a2305n%40googlegroups.com
>  
> .

-- 
You received this message because you are subscribed to the Google Groups 
"pylons-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to pylons-discuss+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/pylons-discuss/cef7546c-e50c-c84c-6a93-40c6b85230b4%40gmail.com.

[pylons-discuss] generating docs for views

2021-03-12 Thread 'Jonathan Vanasco' via pylons-discuss

I had a small Pyramid project which has grown into a much larger one.

Many Views service multiple Routes (multiple calls to `@view_config()`),
typically offering a default HTML version on a "bare" url, and a JSON
version with a ".json" suffix to the url.

Documenting these routes has become increasingly burdensome, and I really
need to simplify it. For clarity, the docs are served by the application
itself and in a structured format.

Right now I have two types of documentation, and I'd like to consolidate it
into a single one.

* The original documentation was built off a Python file, `/lib/docs.py`,
which just notes the routes which have JSON endpoints, gives an "about"
docstring, and offers a dict about how the route functions (GET vs POST, is
it self-documenting, etc).

* As the project progressed, the routes started self-documenting. Forms
were moved to POST only, with GET offering structured details
(instructions, required vs optional form elements, etc). Most of this is
defined by just returning a dict on GET operations.

I've been trying to figure out the best ways to consolidate this. Perhaps
using a custom decorator to declare and track this information into a
namespace?

Has anyone else worked on a scenario like this? How did you handle it?

--
You received this message because you are subscribed to the Google Groups
"pylons-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to pylons-discuss+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/pylons-discuss/2cc3c09f-037a-4cf0-9a18-b464540a2305n%40googlegroups.com.

Re: [pylons-discuss] Pyramid 2.0: Only venusian callbacks with category 'pyramid' are called by default

2021-03-12 Thread Michael Merickel

Estartu,

Thanks for bringing up the issue.

The initial reason I looked into changing it is because I had other venusian 
packages that I did not want scanned and when I dove into the details I could 
not find a good reason why things were the way they were (you can see I looked 
through the history in the original ticket), and I could find some good reasons 
that it should be "pyramid" which I don't think I explained well at all.

My main reason for changing it is that each scan() does have a contract with 
the decorator that needs to be satisfied. All pyramid-compatible decorators 
expect the scanner to have a "config" attribute that is a Pyramid Configurator 
object. That is the contract you get when you use "config.scan()". So if a 
decorator wants the config object, shouldn't it register as the "pyramid" 
category or another custom category passed to scan to guarantee it gets what it 
needs? This seems to be the only safe way to do it with the scan api that is an 
umbrella search through the code.

I tend to prefer explicit over implicit in these types of things which is why I 
advocated for the change and at the time no one advocated for keeping it. Which 
packages are using different categories?

- Michael

> On Mar 12, 2021, at 05:05, Gerhard Schmidt  wrote:
> 
> Hallo Steve,
> 
> I have found the change but there is not reason why this change is needed. It 
> simple states the change. What is the reason behind the change.
> 
> Are there security issues? Which added benefits does it provide? Why is 
> categories=None a bad idea?
> 
> These question aren't answered in the pull request nor in the commit message.
> 
> In the related issue (which was closed in 2012) the final comment was
> 'I'm going to leave "all categories", as we've come to rely on it being the 
> default. If you want to limit it within your application, please pass a set 
> of limiting categories.'
> The whole issuse is about using venusian outside of pyramid. So why change 
> the default in pyramid.
> 
> The change was 7 years after the issue was closed.
> 
> Regards
>   Estartu
> 
> Am 12.03.21 um 11:26 schrieb Steve Piercy:
>>> From the release notes:
>> https://docs.pylonsproject.org/projects/pyramid/en/latest/changes.html#backward-incompatibilities
>> pyramid.config.Configurator.scan will no longer, by default, execute 
>> Venusian decorator callbacks registered for categories other than 'pyramid'. 
>> To find any decorator regardless of category, specify config.scan(..., 
>> categories=None). See https://github.com/Pylons/pyramid/pull/3510
>> That PR in turn fixed:
>> https://github.com/Pylons/pyramid/issues/3502
>> Which in turn referenced:
>> https://github.com/Pylons/pyramid/issues/495
>> I don't know if that answers your question, but please feel free to 
>> elaborate if it does not.  Thank you!
>> --steve
>> On 3/12/21 1:36 AM, Gerhard Schmidt wrote:
>>> Hi,
>>> 
>>> thanks for the work.
>>> 
>>> is there a reason why Configurator.scan() now has a default value of 
>>> ('pyramid',) for categories. In pyramid 1 the default was None.
>>> 
>>> The change causes that only callbacks in category 'pyramid' are called by 
>>> default. If the scanner called with categories=None, venusian asks the 
>>> object which categories are used and invoke all callbacks of the scanned 
>>> package. venusian.attach() stores all uses categories in an attribute of 
>>> the object. So the object knowns all used categories.
>>> 
>>> Some packages use different categories, so there callbacks are not called 
>>> by default. You have either call config.scan with all the categories used 
>>> by your product and all the packages you include or set categories=None 
>>> when calling the config.scan().
>>> 
>>> So is there a reason for this change, because it causes some issues when 
>>> migrating to pyramid 2.0.
>>> 
>>> Regards
>>>Estartu
>>> 
>>> Am 01.03.21 um 04:40 schrieb Michael Merickel:
 Yay, Pyramid 2.0 is out. Get it while it's hot!

 If you're able to run 1.10.8 without deprecation warnings then you're in a 
 great spot to upgrade. Several warnings were added to 1.10.x releases to 
 help you prepare.

 There's shockingly few backward-incompatible changes in this release, so 
 don't let it scare you. There IS a laundry list of new features. Here are 
 a few highlights:

 - First release to drop Python 2, as well as 3.4 and 3.5.

 - New security system for authentication/authorization. The legacy API is 
 deprecated but available and backward compatible. ACLs and principals are 
 not going away, but the policies are merged and restructured slightly 
 which should be more consumable and flexible for users.

 - Several defaults have changed, such as serializing sessions using JSON 
 instead of Pickle.

 - Cookiecutter and tutorials updated with new pytest fixtures.

 - The "pyramid.compat" module is gone.

 Read the "What's New in

[pylons-discuss] Pyramid 2.0: Only venusian callbacks with category 'pyramid' are called by default

2021-03-12 Thread Gerhard Schmidt

Hallo Steve,

I have found the change but there is not reason why this change is
needed. It simple states the change. What is the reason behind the change.

Are there security issues? Which added benefits does it provide? Why is
categories=None a bad idea?

These question aren't answered in the pull request nor in the commit
message.

In the related issue (which was closed in 2012) the final comment was
'I'm going to leave "all categories", as we've come to rely on it being
the default. If you want to limit it within your application, please
pass a set of limiting categories.'
The whole issuse is about using venusian outside of pyramid. So why
change the default in pyramid.

The change was 7 years after the issue was closed.

Regards
Estartu

Am 12.03.21 um 11:26 schrieb Steve Piercy:

From the release notes:

https://docs.pylonsproject.org/projects/pyramid/en/latest/changes.html#backward-incompatibilities

pyramid.config.Configurator.scan will no longer, by default, execute Venusian
decorator callbacks registered for categories other than 'pyramid'. To find any
decorator regardless of category, specify config.scan(..., categories=None).
See https://github.com/Pylons/pyramid/pull/3510

That PR in turn fixed:

https://github.com/Pylons/pyramid/issues/3502

Which in turn referenced:

https://github.com/Pylons/pyramid/issues/495

I don't know if that answers your question, but please feel free to elaborate
if it does not. Thank you!

--steve

On 3/12/21 1:36 AM, Gerhard Schmidt wrote:

Hi,

thanks for the work.

is there a reason why Configurator.scan() now has a default value of
('pyramid',) for categories. In pyramid 1 the default was None.

The change causes that only callbacks in category 'pyramid' are called by
default. If the scanner called with categories=None, venusian asks the object
which categories are used and invoke all callbacks of the scanned package.
venusian.attach() stores all uses categories in an attribute of the object. So
the object knowns all used categories.

Some packages use different categories, so there callbacks are not called by
default. You have either call config.scan with all the categories used by your
product and all the packages you include or set categories=None when calling
the config.scan().

So is there a reason for this change, because it causes some issues when
migrating to pyramid 2.0.

Regards
Estartu

Am 01.03.21 um 04:40 schrieb Michael Merickel:

Yay, Pyramid 2.0 is out. Get it while it's hot!

If you're able to run 1.10.8 without deprecation warnings then you're in a
great spot to upgrade. Several warnings were added to 1.10.x releases to help
you prepare.

There's shockingly few backward-incompatible changes in this release, so don't
let it scare you. There IS a laundry list of new features. Here are a few
highlights:

- First release to drop Python 2, as well as 3.4 and 3.5.

- New security system for authentication/authorization. The legacy API is
deprecated but available and backward compatible. ACLs and principals are not
going away, but the policies are merged and restructured slightly which should
be more consumable and flexible for users.

- Several defaults have changed, such as serializing sessions using JSON
instead of Pickle.

- Cookiecutter and tutorials updated with new pytest fixtures.

- The "pyramid.compat" module is gone.

Read the "What's New in Pyramid 2.0" document for a comprehensive list of
changes and upgrading notes:

https://docs.pylonsproject.org/projects/pyramid/en/2.0-branch/whatsnew-2.0.html

2.0 release documentation:

https://docs.pylonsproject.org/projects/pyramid/en/2.0-branch/

You can install it via PyPI:

pip install Pyramid==2.0

As always report any issues to the issue tracker (or here on the mailing list).

https://github.com/Pylons/pyramid/issues

Special thanks to a few people specifically for their excellent work on this
release:

- Theron Luhn
- Bert JW Regeer
- Steve Piercy

Thanks for everyone's efforts as well as support in getting this work done!

- Pyramid core developers

--
You received this message because you are subscribed to the Google Groups
"pylons-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to
pylons-discuss+unsubscr...@googlegroups.com
.
To view this discussion on the web visit
https://groups.google.com/d/msgid/pylons-discuss/14F179EB-F647-42B7-845A-6091E1AFF697%40gmail.com

--
You received this message because you are subscribed to the Google Groups
"pylons-discuss" group.
To unsubscribe from this group and stop receiving

Re: [pylons-discuss] Pyramid 2.0 released

2021-03-12 Thread Steve Piercy

>From the release notes:

https://docs.pylonsproject.org/projects/pyramid/en/latest/changes.html#backward-incompatibilities

pyramid.config.Configurator.scan will no longer, by default, execute Venusian 
decorator callbacks registered for categories other than 'pyramid'. To find any 
decorator regardless of category, specify config.scan(..., categories=None). 
See https://github.com/Pylons/pyramid/pull/3510

That PR in turn fixed:

https://github.com/Pylons/pyramid/issues/3502

Which in turn referenced:

https://github.com/Pylons/pyramid/issues/495

I don't know if that answers your question, but please feel free to elaborate 
if it does not.  Thank you!

--steve


On 3/12/21 1:36 AM, Gerhard Schmidt wrote:
> Hi,
> 
> thanks for the work.
> 
> is there a reason why Configurator.scan() now has a default value of 
> ('pyramid',) for categories. In pyramid 1 the default was None.
> 
> The change causes that only callbacks in category 'pyramid' are called by 
> default. If the scanner called with categories=None, venusian asks the object 
> which categories are used and invoke all callbacks of the scanned package. 
> venusian.attach() stores all uses categories in an attribute of the object. 
> So the object knowns all used categories.
> 
> Some packages use different categories, so there callbacks are not called by 
> default. You have either call config.scan with all the categories used by 
> your product and all the packages you include or set categories=None when 
> calling the config.scan().
> 
> So is there a reason for this change, because it causes some issues when 
> migrating to pyramid 2.0.
> 
> Regards
>    Estartu
> 
> Am 01.03.21 um 04:40 schrieb Michael Merickel:
>> Yay, Pyramid 2.0 is out. Get it while it's hot!
>>
>> If you're able to run 1.10.8 without deprecation warnings then you're in a 
>> great spot to upgrade. Several warnings were added to 1.10.x releases to 
>> help you prepare.
>>
>> There's shockingly few backward-incompatible changes in this release, so 
>> don't let it scare you. There IS a laundry list of new features. Here are a 
>> few highlights:
>>
>> - First release to drop Python 2, as well as 3.4 and 3.5.
>>
>> - New security system for authentication/authorization. The legacy API is 
>> deprecated but available and backward compatible. ACLs and principals are 
>> not going away, but the policies are merged and restructured slightly which 
>> should be more consumable and flexible for users.
>>
>> - Several defaults have changed, such as serializing sessions using JSON 
>> instead of Pickle.
>>
>> - Cookiecutter and tutorials updated with new pytest fixtures.
>>
>> - The "pyramid.compat" module is gone.
>>
>> Read the "What's New in Pyramid 2.0" document for a comprehensive list of 
>> changes and upgrading notes:
>>
>> https://docs.pylonsproject.org/projects/pyramid/en/2.0-branch/whatsnew-2.0.html
>>  
>> 
>>
>> 2.0 release documentation:
>>
>> https://docs.pylonsproject.org/projects/pyramid/en/2.0-branch/ 
>> 
>>
>> You can install it via PyPI:
>>
>>    pip install Pyramid==2.0
>>
>> As always report any issues to the issue tracker (or here on the mailing 
>> list).
>>
>> https://github.com/Pylons/pyramid/issues 
>> 
>>
>> Special thanks to a few people specifically for their excellent work on this 
>> release:
>>
>> - Theron Luhn
>> - Bert JW Regeer
>> - Steve Piercy
>>
>> Thanks for everyone's efforts as well as support in getting this work done!
>>
>> - Pyramid core developers
>>
>> -- 
>> You received this message because you are subscribed to the Google Groups 
>> "pylons-discuss" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to pylons-discuss+unsubscr...@googlegroups.com 
>> .
>> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/pylons-discuss/14F179EB-F647-42B7-845A-6091E1AFF697%40gmail.com
>>  
>> .
> 

-- 
You received this message because you are subscribed to the Google Groups 
"pylons-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to pylons-discuss+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/pylons-discuss/d2303cbd-e04a-2700-4be6-842128984e0d%40gmail.com.

Re: [pylons-discuss] Pyramid 2.0 released

2021-03-12 Thread Gerhard Schmidt

Hi,

thanks for the work.

is there a reason why Configurator.scan() now has a default value of
('pyramid',) for categories. In pyramid 1 the default was None.

The change causes that only callbacks in category 'pyramid' are called
by default. If the scanner called with categories=None, venusian asks
the object which categories are used and invoke all callbacks of the
scanned package. venusian.attach() stores all uses categories in an
attribute of the object. So the object knowns all used categories.

Some packages use different categories, so there callbacks are not
called by default. You have either call config.scan with all the
categories used by your product and all the packages you include or set
categories=None when calling the config.scan().

So is there a reason for this change, because it causes some issues when
migrating to pyramid 2.0.

Regards
Estartu

Am 01.03.21 um 04:40 schrieb Michael Merickel:

Yay, Pyramid 2.0 is out. Get it while it's hot!

If you're able to run 1.10.8 without deprecation warnings then you're in
a great spot to upgrade. Several warnings were added to 1.10.x releases
to help you prepare.

There's shockingly few backward-incompatible changes in this release, so
don't let it scare you. There IS a laundry list of new features. Here
are a few highlights:

- First release to drop Python 2, as well as 3.4 and 3.5.

- New security system for authentication/authorization. The legacy API
is deprecated but available and backward compatible. ACLs and principals
are not going away, but the policies are merged and restructured
slightly which should be more consumable and flexible for users.

- Several defaults have changed, such as serializing sessions using JSON
instead of Pickle.

- Cookiecutter and tutorials updated with new pytest fixtures.

- The "pyramid.compat" module is gone.

Read the "What's New in Pyramid 2.0" document for a comprehensive list
of changes and upgrading notes:

https://docs.pylonsproject.org/projects/pyramid/en/2.0-branch/whatsnew-2.0.html

2.0 release documentation:

https://docs.pylonsproject.org/projects/pyramid/en/2.0-branch/

You can install it via PyPI:

pip install Pyramid==2.0

As always report any issues to the issue tracker (or here on the mailing
list).

https://github.com/Pylons/pyramid/issues

Special thanks to a few people specifically for their excellent work on
this release:

- Theron Luhn
- Bert JW Regeer
- Steve Piercy

Thanks for everyone's efforts as well as support in getting this work done!

- Pyramid core developers

--
You received this message because you are subscribed to the Google
Groups "pylons-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to pylons-discuss+unsubscr...@googlegroups.com
.
To view this discussion on the web visit
https://groups.google.com/d/msgid/pylons-discuss/14F179EB-F647-42B7-845A-6091E1AFF697%40gmail.com
.

Re: [pylons-discuss] generating docs for views

Re: [pylons-discuss] generating docs for views

[pylons-discuss] generating docs for views

Re: [pylons-discuss] Pyramid 2.0: Only venusian callbacks with category 'pyramid' are called by default

[pylons-discuss] Pyramid 2.0: Only venusian callbacks with category 'pyramid' are called by default

Re: [pylons-discuss] Pyramid 2.0 released

Re: [pylons-discuss] Pyramid 2.0 released

7 matches

Site Navigation

Mail list logo

Footer information