Re: [Python-Dev] str(IntEnum)
On Feb 24, 2015, at 10:56 AM, Guido van Rossum gu...@python.org wrote: It sure seems that way. Thanks for the additional feedback Guido. I’d spent some further time thinking about what it was that I was looking for and determined it was bollocks. The proposal was a poor solution to a specific immediate problem without taking more general use cases into account. My apologies for the noise. signature.asc Description: Message signed with OpenPGP using GPGMail ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] str(IntEnum)
On Feb 20, 2015, at 7:03 PM, Ian Cordasco graffatcolmin...@gmail.com wrote: I hope this helps. It does, as do the other replies, thanks all. To be clear, my first gripe has stemmed into two related (but very minor) problems: 1. IntEnum.__str__. I understand the reasoning behind the current implementation. Personally I’d still prefer it to be consistent with int (and other types as shown above) and if I wanted to know where it came from, I could use repr(), but I understand that this /was/ previously thought out and is contrary to the decision made. I’m fine with being in the minority (or on my own as it seems in this case) and leaving it alone (with the only caveat being the next point). 2. Consistency of __str__ semantics across the standard library and builtins. I believe that the value of __str__ is something that I, as a user, should be able to infer when using disparate types. Unfortunately, some represent the values while other represent the object themselves, nearly the same problem that __repr__ solves minus the requirement of being a valid Python expression where possible. In my mind, a clear separation between __str__ representing the value of an instance and __repr__ representing the object, or where the value came from (and perhaps /not/ having the auto-fallback) makes sense, but would only be one potential solution to promoting consistency. In any event, there are many larger problems to be solved (that is, if anyone else /does/ consider this a problem) and I very well may be on my own with this thinking. signature.asc Description: Message signed with OpenPGP using GPGMail ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] str(IntEnum)
While working on a bug in the issue tracker, I came across something that I thought was a little odd around the behaviour of IntEnum. Should the behaviour of an instance of an IntEnum not be symmetric to an int where possible? For example: class MyEnum(IntEnum): ... FOO = 1 ... MyEnum.FOO == 1 True MyEnum.FOO * 3 == 3 True str(MyEnum.FOO) == str(1) False In my mind, the string representation here should be “1” and not the label. Was this simply an oversight of the specialized IntEnum implementation, or was there a concrete reason for this that I’m not seeing? signature.asc Description: Message signed with OpenPGP using GPGMail ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Fwd: str(IntEnum)
On Feb 20, 2015, at 8:54 AM, Brett Cannon br...@python.org wrote:
Concrete reason. The string is 'MyEnum.FOO' which is much more readable and
obvious where the value came from. The fact that it can be treated as an int
is the same as the reason True and False are subclasses of int; it made
practical sense for compatibility with what they typically replaced, but
where it made more sense to diverge and introduce new behaviour then we did
so.
Thanks Brett, that makes sense and was pretty much what I assumed. Reading the
docs for __str__ does clarify things a bit in that the intention is to be a
string representation of the object and not the value. That said,
implementations seem to vary throughout the standard library and builtins:
str(uuid.uuid4())
'd467d97c-fc09-4dc9-bea5-aeebdad8df8d’
str(int())
‘0'
str(datetime.datetime.now())
'2015-02-20 09:31:28.385539’
str(IPv4Address('127.0.0.1'))
'127.0.0.1'
These and other implementations return a string representation of the
instance’s value, not a string representation of the object itself. Whereas
elsewhere in the standard library:
str(ProtocolError('url', 42, 'msg', ''))
'ProtocolError for url: 42 msg’
str(URLError('reason'))
'urlopen error reason’
str(Cookie(0, '', '', '4', '', '', '', '', '', '', '', 0, '', '', '', ''))
'Cookie = for :4'
The specific problem that I encountered was when swapping an IntEnum
implementation for ints in http.client, which caused a change in logging output
(from int.__str__ to Enum.__str__), which was a bit of a surprise, especially
given the value is a builtin type.
I think that a decent rule around the usage of __str__ is that it should be a
string representation of the value, not of the object. Failing the ability to
logically coerce the value to a string, it should simply fall back to repr(obj).
Of course, I realize that the chances of this change being made to such a
fundamental (and largely inconsequential) feature are likely nil, but I thought
I’d share my thoughts anyways.
signature.asc
Description: Message signed with OpenPGP using GPGMail
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Overriding stdlib http package
On 2015-01-24 7:17 AM, Donald Stufft wrote: It’s not just power users that it’s good for, it makes it harder for even beginners to use things like backports of modules. What about cases where new module versions are put in as dependencies of other packages and they stomp standard library packages unbeknownst to the user installing the higher level package? For example, let's say packageB overrides stdlib's packageA. packageC requires packageB, which stomps packageA at import time. Now, author of packageD requires packageC but is unaware of the fact that packageB overrides packageA, but heavily uses packageA directly and expects the stdlib behavior, not the modified behavior in packageB. (Hope I got the hierarchy right in that description ;)) This would likely cause unexpected behavior and I can only assume that it would likely be quite difficult to track down, even for a power user. The same logic applies to unrelated stdlib modules that depend on the stdlib behavior of packageA as Brett pointed out. As someone who's recently faced the problem, while making it easier would have been immediately beneficial to me as the module author, I can understand the reasoning behind making this a difficult thing to do. I /do/ think that it might be worthwhile to invest some time in making it easier to do while still satisfying the safety of other packages, but I would venture to say it would definitely be non-trivial. signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Overriding stdlib http package
On 2015-01-14 11:35 AM, Guido van Rossum wrote: Why do you want to hack the existing http modules? This is not a rhetorical question. The answer may lead us to redesign the existing http modules to be more flexible so that the higher-level problem you are trying to solve by hacking http import can be solved instead by using an interface provided by the stdlib http module. Sorry, this venture began in core-mentorship, so a little context may be of use: My end goal is to become a maintainer of the http package. As I'm not a core dev, Nick had suggested making a friendly fork of the package in order to facilitate progress without being bound to the non-core dev contributor workflow (it can, at times, be a little painful getting reviews and such completed on orphaned packages). So, the question that I was trying to answer isn't directly related to the http package in particular, but how to override stdlib modules in general with a third party package in order to facilitate out of band development while making minimal changes to package code (i.e. changing all absolute import package names in test and module code) to ease upstream merging. That all said, this would likely be a moot issue if I had commit privileges ;) But it might be nice to figure out a good workflow should this come up again with any other new contributors looking to take ownership of an orphaned module. signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Overriding stdlib http package
On 2015-01-14 12:25 PM, Guido van Rossum wrote: I'm not sure how commit privileges would help you -- can't you just fork the CPython (I'm sure there's already a Bitbucket mirror that you can fork easily) and do your work there? Even with commit privileges you wouldn't be committing partial work unreviewed. The friendly module fork allows for others to easily (or at least the intention is to do it easily) use the module with the new, backwards compatible features as a drop in replacement for the stdlib module. Giving others the ability to do this would lend itself to the adoption of the module and bug reports and such before upstream patches are produced. That said, the main downside to the friendly fork is the patch submission process: After changes have been merged to the fork, there's bound to be churn during the upstream patch submission, which would likely lead to something that looks like: Implement feature/bug fix [1] Commit changes to httlib3 Generate patch for CPython Import patch to local CPython Run unit tests [1] Generate hg patch (patchA) for submission to bug tracker Upload patchA patchA is reviewed Implement review changes and generate patchB [1] Upload patchB [...wait for merge...] Merge delta of patchB and patchA to httplib3 Test/upload new PyPI package I see commit privileges helping in two ways: 1. I've experienced lag on a few occasions between review and merge. I'm assuming that this is largely due to a lack of dotted line maintainer of the http package (although I believe that the general consensus is that Senthil is the de facto maintainer of the package). Commit privileges would help in getting the patches merged once reviews are complete. 2. It would help my own workflow. While feature development can be done in httplib3, I do also tend to swap between issues in the bug tracker and large feature work. Because I have two lines of work (CPython/bug tracker and Github), I run into issues around where these changes should be made: Should the bug fixes live in CPython/bug tracker or should I fix the issue in httplib3 and go through the submission workflow above? Either way, I'm signing myself up for a good deal of headache managing the httplib3 work, especially when development work across feature branches is dependent on patches submitted to CPython. I definitely don't mind the extra work if there are no other options, but my end goal is to be a maintainer of the http package and core developer, not to maintain a third party fork. signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Overriding stdlib http package
On 2015-01-14 1:19 PM, Brett Cannon wrote: But as Guido pointed out, we _like_ it being difficult to do because we don't want this kind of substitution happening as code ends up depending on bugs and quirks that you may fix. I can understand the reasoning. How many other modules are dependent on the http module in the stdlib that are going to be affected by your changes? One option is you fork http **and** and modules in the stdlib that are dependent on it. You don't really have to change the other modules beyond their import statement of using http -- you can even do `import http3 as http` or something to minimize the changes -- but you at least don't have to monkeypatch sys.modules for others to gain from your http changes. Plus as you patch stuff in http you may find you have/want to patch other dependent modules as well and so you will have already done that. It looks like there are 5 other modules dependent on the http package. If I understand what you're proposing, it pretty much defeats the purpose of what I'm trying to accomplish with a standalone httplib3 package. That said, considering the points that you and Guido have both made, I think that the best course of action is to either just fork CPython as a whole or to continue with httplib3 but abandon overriding sys.modules, develop features detached from the stdlib and worry about fixing dependencies when integrating changes upstream. signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Overriding stdlib http package
Apologies for the double send, apparently Thunderbird got confused when going through a 4G dead zone. I should mention that I'm aware that any module that previously imported the stdlib version would retain that version rather than a reference to the new one, but I'm okay with that as this is a very specific use case: Having imports across tests and package modules use httplib3 to facilitate merging changes back upstream. On 2015-01-14 8:32 AM, Demian Brecht wrote: Hi all, As part of the work I'm doing on httplib3 (now that I've actually gotten a bit of time), one of the things I'm trying to get done is injection of httplib3 over http in order to not have to modify all import paths in modules and such. Here's the gist of what I have so far: https://gist.github.com/demianbrecht/bc6530a40718e4fcbf90. It's greatly simplified over importlib2's inject mechanism, but I'm assuming that's largely due to requirements of that package (i.e. Python 2) in contrast to this one. My question is: Does this look sane? Is there anything that I might be not accounting for? It /does/ seem to work as expected when running tests, but I'm curious if there's anything that I might be missing that might jump out at someone more intimately familiar with the mechanics of importlib. Thanks, Demian signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Overriding stdlib http package
Hi all, As part of the work I'm doing on httplib3 (now that I've actually gotten a bit of time), one of the things I'm trying to get done is injection of httplib3 over http in order to not have to modify all import paths in modules and such. Here's the gist of what I have so far: https://gist.github.com/demianbrecht/bc6530a40718e4fcbf90. It's greatly simplified over importlib2's inject mechanism, but I'm assuming that's largely due to requirements of that package (i.e. Python 2) in contrast to this one. My questions are: Does this look sane? Is there anything that I might be not accounting for? It /does/ seem to work as expected when running tests, but I'm curious if there's anything that I might be missing that might jump out at someone more intimately familiar with the mechanics of importlib. Thanks, Demian signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Overriding stdlib http package
Hi all, As part of the work I'm doing on httplib3 (now that I've actually gotten a bit of time), one of the things I'm trying to get done is injection of httplib3 over http in order to not have to modify all import paths in modules and such. Here's the gist of what I have so far: https://gist.github.com/demianbrecht/bc6530a40718e4fcbf90. It's greatly simplified over importlib2's inject mechanism, but I'm assuming that's largely due to requirements of that package (i.e. Python 2) in contrast to this one. My question is: Does this look sane? Is there anything that I might be not accounting for? It /does/ seem to work as expected when running tests, but I'm curious if there's anything that I might be missing that might jump out at someone more intimately familiar with the mechanics of importlib. Thanks, Demian signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Overriding stdlib http package
I had considered that but thought that dev might be more appropriate as it's related to overriding a stdlib module in order to work on that module out of band with cpython (with the intention of merging back upstream). I would imagine those on the dev list may be better suited to answer. On Wed, Jan 14, 2015, 08:37 Ian Cordasco graffatcolmin...@gmail.com wrote: I think this belongs on python-list, not python-dev. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Overriding stdlib http package
Hm, I /did/ try that but ran into issues. Swapping the custom finder for the monkey patch now seems to work as expected though. Could be that I was doing something else at the time that caused it not to work. I'll keep running with that and will ping the thread if the issues surface again. Thanks! On 2015-01-14 8:54 AM, Antoine Pitrou wrote: What don't you simply monkeypatch sys.modules, e.g.: import myhttplib sys.modules['http'] = myhttplib or doesn't it work as desired? signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Cpython code and ...
It denotes a variadic function:
http://www.gnu.org/software/libc/manual/html_node/Variadic-Functions.html.
On 2015-01-07 11:07 AM, Ethan Furman wrote:
I found this:
PyObject *
PyBytes_FromFormat(const char *format, ...)
{
Can someone enlighten me on what the '...' means?
--
~Ethan~
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/demianbrecht%40gmail.com
signature.asc
Description: OpenPGP digital signature
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP 481 - Migrate Some Supporting Repositories to Git and Github
On Tue, Dec 2, 2014 at 9:23 AM, Tres Seaver tsea...@palladion.com wrote: I'd vote for experimentation, to ground the discussion in actual practice. +1. There may be a number of practical gotchas that very well might not surface in PEPs and should be documented and planned for. Likewise with benefits. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] hg vs Github [was: PEP 481 - Migrate Some Supporting Repositories to Git and Github]
hg vs Github At best, this is apples to oranges in comparing a DVCS to a platform, or was the intention to change the subject to hg vs git? If so, then it's promoting a developer tool war in the same vein as the never ending vim vs emacs and will likely only result in continued dissension. IMHO, there's really no point in continuing this discussion past decisions to be made by a select few in the thread discussing PEP 481. On Mon, Dec 1, 2014 at 9:56 AM, Fred Drake f...@fdrake.net wrote: On Mon, Dec 1, 2014 at 12:37 PM, Jim J. Jewett jimjjew...@gmail.com wrote: I think even the proponents concede that git isn't better enough to justify a switch in repositories. There are also many who find the Bitbucket tools more usable than the Github tools. I'm not aware of any functional differences (though I don't often use Github myself), but the Bitbucket UIs have a much cleaner feel to them. -Fred -- Fred L. Drake, Jr.fred at fdrake.net A storm broke loose in my mind. --Albert Einstein ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/demianbrecht%40gmail.com -- Demian Brecht https://demianbrecht.github.io https://github.com/demianbrecht ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP 481 - Migrate Some Supporting Repositories to Git and Github
On Sat, Nov 29, 2014 at 3:27 PM, Donald Stufft don...@stufft.io wrote: As promised in the Move selected documentation repos to PSF BitBucket account? thread I've written up a PEP for moving selected repositories from hg.python.org to Github. FWIW, I'm a pretty solid -1 to this PEP. Don't get me wrong, I'm much more accustomed to git than I am hg, much prefer git's lightweight branching model and would love to see CPython and all ancillary repos migrated to git Github. If that was what this PEP was after, I'd be a +1. What I don't like about it is the introduction of multiple tools that directly impact the barrier of entry to contributing. I think that splitting ancillary repos such as PEPs and docs out might be a little short sighted at an overall project level. In my mind, there are three major categories of contributors (and prospective contributors): 1. Those that use git on a daily basis 2. Those that use hg on a daily basis 3. Those who use neither and are more accustomed to Perforce, SVN and the like Let's say this PEP is approved and the suggested repos are moved to Github. For git users, life is suddenly made much easier when contributing to those projects for obvious reasons. However, they still have the same barrier of entry to contributing to CPython (I would imagine that this would be the goal for most users, but maybe I'm wrong about that). I would imagine that contributing to the ancillary repos would be great grounds to ramp up on using hg before hitting CPython with its multiple long lived branches and such. Making the switch as suggested by this PEP removes that. For hg users, you now add a barrier of entry for contributing to the repos now living on Github. In both cases, you've introduced the need to context switch when contributing to CPython and any of the other repos. Two tools that require quite different workflows. Then, for the third class of users, you've now introduced the requirement of learning two different sets of tools (if they want to do anything outside of using the Edit button through Github's UI). Now you're looking at conflated contributor documentation or project-specific documentation. IMHO, suboptimal either way you look at it. Personally, I don't think that there are any silver bullets to this problem. In no case is everyone going to be satisfied. In cases like that, I tend to think that no matter what the solution eventually agreed upon is, consistency is of the utmost importance. Moving a number of repos to Github breaks that consistency. What *would* be nice if CPython was to stay on mercurial though is perhaps moving those repos to Bitbucket. In that case, you get both the Edit feature that really by all account removes the initial bar of entry, but you still remain consistent with the rest of the project. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Move selected documentation repos to PSF BitBucket account?
On Tue, Nov 25, 2014 at 6:52 AM, Brett Cannon br...@python.org wrote: I suspect if we make sure we add Bitbucket and GitHub login support to the issue tracker then that would help go a fair distance to helping with the GitHub pull of reach (and if we make it so people can simply paste in their fork's URL into the issue tracker and we simply grab a new patch for review that would go even farther). Chiming in horribly late, so hopefully this hasn't already been mentioned (I've only loosely been following this thread). In addition to the login support (I'm not sold on how much that would help the reach), I think it would be really beneficial to have some documentation on either emulating git-style workflow in hg or detailing a git fork workflow while working on multiple patches concurrently and keeping master in sync with hg default (or perhaps even both). I primarily use git for development. Having little or no effort to context switch to work on CPython in any capacity (PEPs, code, etc) would be hugely beneficial for me. Having a well defined workflow in the docs (perhaps alongside Lifecycle of a patch?) would have significantly lowered the initial barrier of entry for me. Given the amount of time I put into that initially, I can only imagine how many people it's entirely turned away from contributing. I'd definitely be interested in contributing documentation around this (I've written up something similar here http://demianbrecht.github.io/vcs/2014/07/31/from-git-to-hg/) if others feel that it would be valuable. IMHO, you don't want to limit submissions due to the tech stack (one of the arguments I've seen for not moving to Github was quality of submissions). This will also limit high quality work from those who simply don't have time to adopt new tech and workflows when they're not being paid to do so. I have no strong opinion of where and how the official repos are stored so long as I can work on them and contribute to them in the way that's most efficient for me. I imagine that statement would also hold true for most. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Why is documentation not inline?
This is more out of curiosity than to spark change (although I wouldn't argue against it): Does anyone know why it was decided to document external to source files rather than inline? When rapidly digging through source, it would be much more helpful to see parameter docs than to either have to find source lines (that can easily be missed) to figure out the intention. Case in point, I've been digging through cookiejar.py and request.py to figure out their interactions. When reading through build_opener, it took me a few minutes to figure out that each element of *handlers can be either an instance /or/ a class definition (I was looking at how to define a custom cookiejar for an HTTPCookieProcessor). Yes, I'm (now) aware that there's some documentation at the top of request.py, but it would have been helpful to have it right in the definition of build_opener. It seems like external docs is standard throughout the stdlib. Is there an actual reason for this? Thanks, -- Demian Brecht http://demianbrecht.github.com ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Why is documentation not inline?
@benjamin: Ah, i see. I wasn't around pre-Sphinx. However, unless there's some custom build steps that I'm unaware of that may prevent it, it should still be relatively easy to maintain the desired narrative structure as long as the inline API docs are kept terse. @antoine: Sorry, I may not have been clear. I wasn't advocating the inclusion of the /entire/ doc pages inline. I'm advocating terse documentation for the stdlib APIs and parameters. Narrative documentation can (and should be) maintained externally, but could use autodoc to include the terse references when desired. This would ensure that the same docs are available (and consistent) when reading the documentation as well as when neck-deep in code. On Sun, May 19, 2013 at 3:32 PM, Antoine Pitrou solip...@pitrou.net wrote: On Sun, 19 May 2013 15:29:37 -0700 Demian Brecht demianbre...@gmail.com wrote: This is more out of curiosity than to spark change (although I wouldn't argue against it): Does anyone know why it was decided to document external to source files rather than inline? When rapidly digging through source, it would be much more helpful to see parameter docs than to either have to find source lines (that can easily be missed) to figure out the intention. Case in point, I've been digging through cookiejar.py and request.py to figure out their interactions. When reading through build_opener, it took me a few minutes to figure out that each element of *handlers can be either an instance /or/ a class definition (I was looking at how to define a custom cookiejar for an HTTPCookieProcessor). Yes, I'm (now) aware that there's some documentation at the top of request.py, but it would have been helpful to have it right in the definition of build_opener. It seems like external docs is standard throughout the stdlib. Is there an actual reason for this? Have you seen the length of the documentation pages? Putting them inline in the stdlib module would make the code much harder to skim through. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/demianbrecht%40gmail.com -- Demian Brecht http://demianbrecht.github.com ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Why is documentation not inline?
@nick: Yes, I realize what docstrings are for (I should have used that term rather than inline docs, my bad there :)). I think the problem that I've run into is simply inconsistencies in methods of documenting code (and the few times that it would have been helpful, what I was looking at had not been authored using docstrings). Is the usage of docstrings a requirement (or a strong suggestion) for new commits (I didn't see anything while reading the submission guidelines)? If not, would it perhaps be a worthy addition? On Sun, May 19, 2013 at 4:51 PM, Nick Coghlan ncogh...@gmail.com wrote: On 20 May 2013 08:51, Demian Brecht demianbre...@gmail.com wrote: @benjamin: Ah, i see. I wasn't around pre-Sphinx. However, unless there's some custom build steps that I'm unaware of that may prevent it, it should still be relatively easy to maintain the desired narrative structure as long as the inline API docs are kept terse. That's what docstrings are for - abbreviated docs for use when reading the code and at the interactive prompt. The prose docs are designed to be a more discursive introduction to the full details of each operation, whereas docstrings are usually written more to provide someone that already knows what the function does with a reminder of the details. Cheers, Nick. @antoine: Sorry, I may not have been clear. I wasn't advocating the inclusion of the /entire/ doc pages inline. I'm advocating terse documentation for the stdlib APIs and parameters. Narrative documentation can (and should be) maintained externally, but could use autodoc to include the terse references when desired. This would ensure that the same docs are available (and consistent) when reading the documentation as well as when neck-deep in code. On Sun, May 19, 2013 at 3:32 PM, Antoine Pitrou solip...@pitrou.net wrote: On Sun, 19 May 2013 15:29:37 -0700 Demian Brecht demianbre...@gmail.com wrote: This is more out of curiosity than to spark change (although I wouldn't argue against it): Does anyone know why it was decided to document external to source files rather than inline? When rapidly digging through source, it would be much more helpful to see parameter docs than to either have to find source lines (that can easily be missed) to figure out the intention. Case in point, I've been digging through cookiejar.py and request.py to figure out their interactions. When reading through build_opener, it took me a few minutes to figure out that each element of *handlers can be either an instance /or/ a class definition (I was looking at how to define a custom cookiejar for an HTTPCookieProcessor). Yes, I'm (now) aware that there's some documentation at the top of request.py, but it would have been helpful to have it right in the definition of build_opener. It seems like external docs is standard throughout the stdlib. Is there an actual reason for this? Have you seen the length of the documentation pages? Putting them inline in the stdlib module would make the code much harder to skim through. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/demianbrecht%40gmail.com -- Demian Brecht http://demianbrecht.github.com ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com -- Demian Brecht http://demianbrecht.github.com ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] FileCookieJars
On 2013-03-11 5:44 AM, R. David Murray wrote: though some patience and persistence may be required. I have a wife and kids. This, I've become quite good at ;) Take a look at http://bugs.python.org/issue2193 (for example), and see if you still want to tackle this topic :) (I hope you do). Egad. I knew that cookies were quite the can of worms prior to digging into this as much as I have, but I didn't realize that the RFC had been written /after/ cookie implementations had already surfaced in the wild (I guess I shouldn't have actually been surprised either). Just makes this more challenging and therefore interesting to work on imo :) The other reality is that our cookie support won't be very useful if it adheres strictly to the RFCs, since the servers and browsers don't. What we need is something practical...which may differ to a greater or lesser degree from what we currently have. Yes, I wasn't sure of the general standpoint of Python stdlibs in terms of practicality versus strict adherence. While adhering to Postel's law in cases such as cookies can definitely make an implementation much more tricky, it increases its practical usage (I didn't realize just how deviant servers and browsers were for this particular topic until after reading through issue 2193). But there is, and in fact it *is* useful and used by many people, so IMO it is worth maintaining. I see your point here and agree. It's much different when changes can be dictated in closed source packages (what I'm most accustomed to) than dealing with an open source project at the scale of Python and the stdlib. Excellent. If you aren't already on the core-mentorship mailing list, you might want to sign up. Your approach (adopting modules without current maintainers) is a good one. Thanks, I wasn't aware of the core-mentorship list. I'll be signing up shortly. Good to know my approach is sane :) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] FileCookieJars
On 2013-03-10 1:59 PM, R. David Murray wrote: To be clear, just passing the stdlib tests is*not* sufficient to think that backward compatibility is not likely to be broken. Deciding about the likelihood of breakage is a hard problem, to which we generally employ gut-level heuristics:) (And code search, as Steven suggests). I figured that this would be a hard problem, which is also why I didn't delve into a patch further than a proposed first stab at a more sane implementation, coupled with changes to the unit tests. Since you say that it will obviously break backward compatibility, I'd say that if we are going to do anything we'd have to think about how best to introduce a more sane implementation and deprecate the old...and if we are going to do that, we probably ought to spend a bit of time seeing if there are any other open cookiejar issues we can tackle at the same time. I was hoping that there would be a little more interest (and potentially some further historical context on why the module was implemented as it was) from those in the group. If, that is, you are interested enough to continue to be the point person for this, which probably won't be a short process:) I'm not sure who this was directed to (me or Steven), but I was looking for an area in the stdlib that I could really sink my teeth into and get my hands dirty with and this definitely seems to be just that. I figured that it wouldn't be a short process and the more that I read up on RFC 6265 (and 2965) and compare them to the implementation in cookie and cookiejar, the more I'm thinking that this will be a relatively complex and lengthy process. (Definitely interested in that btw :)). The problem here is getting people interested, apparently:( Since I start my Pycon diversion-from-work next week, maybe I can find some time to take at least a preliminary look. In case you haven't already seen it, I had posted a second patch (that doesn't break the Liskov substitution principle as Terry pointed out after reviewing my overzealous initial patch) here: http://bugs.python.org/issue16901. I think the design is much more sane than what's currently there and aligns with how HTTP cookies are processed in urllib.request. Now having said all that, the more I think about it and the more I read, the more I wonder why there are even specialized implementations (LWP and Mozilla) in the stdlib to begin with. I would assume that the only thing that the stdlib /should/ be covering is the RFC (6265, but still allowing 2965). If there are deviations (and some are eluded to throughout the code), then I would think that those should be handled by packages external to the stdlib. It seems that the Mozilla implementation covers 2965, but LWP is based on the Perl library (which isn't known to be supported by any browser environment). Why is this even there to begin with? To paraphrase the comments that I read in the code: This isn't supported by any browser, but they're easy to parse. In my mind, this shouldn't be reason enough for inclusion in the stdlib. I'd also go as far to say that if cookies are implemented as consistently as, say, OAuth 2.0 providers (meaning very little to no consistency), then there really shouldn't be a cookie implementation in the stdlib anyway. So to sum it up, yes I'm very much interested in doing what I can to help the development of the stdlib (more so interested in parts that don't currently have experts listed, such as http and imaplib), but will definitely need to be shown the ropes a bit as my professional life has revolved around closed source games. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] FileCookieJars
On 2013-03-10 2:36 PM, Terry Reedy wrote: A) For similar reasons, I consider the proposal a first draft, and probably not the exact right thing to do. That is correct. The more I think about it, the more I'm convincing myself that even though the proposal is more sane than what's there right now, it's definitely not the exact correct thing to do. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] FileCookieJars
Cross-posting from python-ideas due to no response there. Perhaps it's due to a general lack of usage/caring for cookiejar, but figured /someone/'s got to have an opinion about my proposal ;) Note that I've moved my discussion from bug 16942 to 16901 (http://bugs.python.org/issue16901) as they're duplicates and 16901 is more succinct. I've also posted a patch in 16901 implementing my proposal. TL;DR: CookieJar FileCookieJar *CookieJar are architecturally broken and this is an attempt to rectify that (and fix a couple bugs along the way). --- Context: http://bugs.python.org/issue16942 (my patch, changing FileCookieJar to be an abc, defining the interfaces for *FileCookieJar). This pertains to Terry's question about whether or not it makes sense that an abstract base class extends a concrete class. After putting in a little thought, he's right. It doesn't make sense. After further thought, I'm relatively confident that the hierarchy as it stands should be changed. Currently what's implemented in the stdlib looks like this: CookieJar | FileCookieJar | | | MozillaCookieJar LWPCookieJar What I'm proposing is that the structure is broken to be the following: FileCookieJarProcessor CookieJar | | | MozillaCookieJarProcessor LWPCookieJarProcessor The intention here is to have processors that operate /on/ a cookiejar object via composition rather than inheritance. This aligns with how urllib.request.HTTPCookieProcessor works (which has the added bonus of cross-module consistency). The only attributes that concrete FileCookieJarProcessor classes touch (at least, in the stdlib) are _cookies and _cookies_lock. I have mixed feelings about whether these should continue to be noted as non-public with the _ prefix or not as keeping the _ would break convention of operating on non-public fields, but am unsure of the ramifications of changing them to public. Making this change then allows for FileCookieJar(Processor) to be an abstract base class without inheriting from CookieJar which doesn't make a whole lot of sense from an architecture standpoint. I have yet to see what impact these changes have to the cookiejar extensions at http://wwwsearch.sf.net but plan on doing so if this approach seems sound. This will obviously break backwards compatibility, so I'm not entirely sure what best practice is around that: leave well enough alone even though it might not make sense, keep the old implementations around and deprecate them to be eventually replaced by the processors, or other ideas? -- Demian Brecht http://demianbrecht.github.com ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Fwd: request._parse
Sounds good to me, thanks for the feedback.. Yes, I guess tackling known issues is a much better use of time than trying to dig my own up ;) If you want to be helpful, leave _parse along and find a real bug to work on ;-). There are several urllib bug issues. Or check out the code coverage of some test module (see devguide), and see if more tests are needed. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Python 2.7 buffer and memoryview documentation (issue# 17145)
http://bugs.python.org/issue17145 I'm curious as to whether or not anyone has reviewed the documentation update I made here. Context: Having both memory views and buffers in 2.7 (as well as the C-level API for each) is confusing. The initial bug report was to implement consistent behavior for objects supporting the new C-level buffer API or to update the docs. As new features are not being added to 2.7 (as pointed out by Stefan Krah), I made an update to the docs that I think made the disparity between the two (and when one should favour the usage of either) a little clearer. But maybe I'm off my rocker ;) Also, are contributor agreements also required for documentation? Thanks, Demian Brecht http://demianbrecht.github.com ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
