Re: A trivial question that I don't know - document a function/method
On 10/22/2022 4:58 PM, Paulo da Silva wrote: Hi all! What is the correct way, if any, of documenting a function/method? 1. def foo(a,b): """ A description. a: Whatever 1 b: Whatever 2 """ [snip] 5. Any other ... Any comments/suggestions are welcome. Thanks. Paulo This is not a trivial question - not because it is hard but because it is important, and more so when someone else needs to work with your code. It's surprising how easy it is to forget these details about even your own code. Here are some examples of how I like to document functions and methods, mostly based on PEP-257, Docstring Conventions (https://peps.python.org/pep-0257/) and Guido's style guide before it. def make_title_from_headline(self, p, h): """From node title, return title with over- and underline- strings. The leading symbol is chosen based on the indent level of the node. Note that might different from p.h because of, e.g., directive removal. ARGUMENTS p -- the node position whose indent level is to be used. h -- the headline string to be processed. RETURNS a string """ Key points - include all the arguments and the return. Capitals help lead the eye to the ARGUMENT and RETURNS blocks. If you use keyword arguments, add a KEYWORD ARGUMENTS section. def plot(self, stackposition=MAIN, clearFirst=True): """Plot a 2-D graph. ARGUMENTS self -- an instance of a PlotManager stackposition -- an integer denoting which data set to plot. clearFirst -- True if the previous plot should be cleared, else False. RETURNS nothing """ Key point -- if the function/method returns nothing, say so. class Dataset: '''Class to represent a 2D curve. ATTRIBUTES xdata, ydata -- sequences holding the x or y data sets. Must be the same length. May be lists or numpy ndarrays. auxDataset -- dictionary of auxiliary data sets (e.g., for holding statistical information) errorBands -- List of Datasets to hold errors orig_filename -- file path, if any, used to load data (before any transformations have been applied). xaxislabel -- label text for the X axis label yaxislabel -- label text for the Y axis label figurelabel -- label text for the graph of this data ymin -- minimum value for Y axis ymax -- maximum value for Y axis parms -- dictionary of parameters, Meant to store the current values so they can be written to a file. ''' If you have the space, these annotations could instead be placed in-line in the class's __init__() method. But it's not often there is enough space, and when they are in the docstring they will be extracted and displayed by docstring tools, which is a good thing. Sometimes it can happen that a function/method is is simple and clear that its name, and the names of the arguments, make it obvious what their meaning is. But that happens less often than you might think. - Be concise, but choose clarity over brevity; - Try to devise good, descriptive names as far as possible; - A long list of arguments probably should be ordered alphabetically, but could also be grouped, with each group ordered. Otherwise, it is useful to list the parameters in the order they appear in the function/method signature. - Be consistent in your docstrings, but remember there will be times that it makes more sense to relax the consistency. -- https://mail.python.org/mailman/listinfo/python-list
Re: A trivial question that I don't know - document a function/method
I don't think there is a "correct" way. It depends somewhat on what tools you're using. I like pydocstyle, which I have hung off of vim with syntastic. pydocstyle checks for https://peps.python.org/pep-0257/ conformance. Also, rather than describe the types of formal parameters to functions in a docstring, I like to use mypy for https://peps.python.org/pep-0484/ with its --disallow-untyped-calls and --ignore-missing-imports options, which I hang off of a Makefile, called by a vim macro. On Sat, Oct 22, 2022 at 3:39 PM Paulo da Silva < p_d_a_s_i_l_v_a...@nonetnoaddress.pt> wrote: > Hi all! > > What is the correct way, if any, of documenting a function/method? > > 1. > def foo(a,b): > """ A description. > a: Whatever 1 > b: Whatever 2 > """ > ... > > 2. > def foo(a,b): > """ A description. > a -- Whatever 1 > b -- Whatever 2 > """ > ... > > 3. > def foo(a,b): > """ A description. > @param a: Whatever 1 > @param b: Whatever 2 > """ > ... > > 4. > def foo(a,b): > """ A description. > :param a: Whatever 1 > :param b: Whatever 2 > """ > ... > > 5. > Any other ... > > Any comments/suggestions are welcome. > Thanks. > Paulo > > -- > https://mail.python.org/mailman/listinfo/python-list > -- https://mail.python.org/mailman/listinfo/python-list
A trivial question that I don't know - document a function/method
Hi all! What is the correct way, if any, of documenting a function/method? 1. def foo(a,b): """ A description. a: Whatever 1 b: Whatever 2 """ ... 2. def foo(a,b): """ A description. a -- Whatever 1 b -- Whatever 2 """ ... 3. def foo(a,b): """ A description. @param a: Whatever 1 @param b: Whatever 2 """ ... 4. def foo(a,b): """ A description. :param a: Whatever 1 :param b: Whatever 2 """ ... 5. Any other ... Any comments/suggestions are welcome. Thanks. Paulo -- https://mail.python.org/mailman/listinfo/python-list
Re: error
On 2022-10-22 04:43, ishar jaiswal wrote: my problem is not solving i sended you a message when i open python there one error comes. then you why not taking action [image: Screenshot (2).png] This list does not accept screenshots. Please copy and paste the error. -- https://mail.python.org/mailman/listinfo/python-list
Re: Need help with custom string formatter
Cameron Simpson wrote: > Stefan's code implements it's own format_field and falls back to the > original format_field(). That's standard subclassing practice, and worth > doing reflexively more of the time - it avoids _knowing_ that > format_field() just calls format(). > > So I'd take Stefan's statement above to imply that calling format() > directly should work. Yup, makes sense. -- https://mail.python.org/mailman/listinfo/python-list
error
my problem is not solving i sended you a message when i open python there one error comes. then you why not taking action [image: Screenshot (2).png] -- https://mail.python.org/mailman/listinfo/python-list
Re: for -- else: what was the motivation?
the fuck? On Sat, Oct 22, 2022 at 9:06 AM Peter J. Holzer wrote: > On 2022-10-19 12:10:52 +1100, Chris Angelico wrote: > > On Wed, 19 Oct 2022 at 12:01, Peter J. Holzer wrote: > > > On 2022-10-17 09:25:00 +0200, Karsten Hilbert wrote: > > > > http://literateprogramming.com/ > > > > > > Right. That's one of the inspirations for my comment. > > > > > > But literate programming is of course still very much rooted in the > > > "linear text representation" paradigm. You have one definite source > > > which is a linear text. > > > > > > In a world of IDEs, databases and hypertext that's probably not the > best > > > we can do. As Raymond Hettinger would say, "there must be a better > way". > > > > > > It would be very different from mainstream programming languages, > > > however. And ideally you would want it to integrate with a lot of other > > > infrastructure. So that alone might make it a non-starter, even if it > > > was really good (which realistically early iterations wouldn't be). > > > > There are special-purpose languages like Scratch which are not simple > > text in that form. > > Yes, I know. > > It has a different goal though: Scratch tries to establish a friendly > learning environment. Get rid of typing and syntax errors that beginners > find so frustrating. > > What I'm interested in is an enviroment for developing medium-sized real > applications. Somewhere in the several person-months to several > person-years of effort, hundreds of user-stories, maybe thousands of > bug-reports and change-requests over its life-time. > > The people using such a system/language would be professional > programmers. They probably don't need much help to get the syntax of a > for loop right. What they do need, though: > > * Cross-reference between requirements and code. (Yes, you can write > comments, yes, you will hopefully have meaningful commit messages. > Still, I see a lot of room for improvements there) > * Cross-references between related parts of the code. (Yes, many IDEs > can jump to the definition of an instance or list all instances of a > definiton, But sometimes the relationship isn't that mechanic. And > yes, you can use comments fpr that, too) > * Views which highlight some parts of the code and omit others. (Folding > editors do that in a very limited fashion) > * For example, I might want to see only the code proper when I'm > focusing on an algorithm or I might want to see lots of context > (type definitions, requirements, test results, ...) > * Classes often have quite a lot of methods with no natural order. > Being able to view only a subset of them in some custom order may > help. > * Going back to the core idea of literate programming: Especially > views which show some requirement(s) together with the code that > implements them plus some explanation why that implementation was > chosen. > > Presented like this, it's clear that the "language" (i.e. the file > format) is probably the smallest part of the problem. How the user can > view the program, how they can edit it, and how to keep the whole thing > manageable is a much bigger question. And it would probably be a good > idea to start at the system level and not at the language level. > > > > My Twitch channel bot has a command executor whose language, if you > > call it that, is basically JSON - and the way to edit those commands > > is very Scratch-inspired. > > I designed a graphical filter language for database queries once. The idea > was that you could combine various operations (selects, projections, > grouping, transformations, ...) into pipelines via a web interface. We > did implement it (sadly it wasn't me who did it), and it turned out to > be a lot harder than I thought to make that actually usable. > > And of course there have been lots of CASE tools over the years. That > seems to have been mostly a fad of 90s. Still, there were some good > ideas there (although not alway implemented well), and something bubbles > back up every now and then. > > hp > > -- >_ | Peter J. Holzer| Story must make more sense than reality. > |_|_) || > | | | h...@hjp.at |-- Charles Stross, "Creative writing > __/ | http://www.hjp.at/ | challenge!" > -- > https://mail.python.org/mailman/listinfo/python-list > -- https://mail.python.org/mailman/listinfo/python-list
Re: for -- else: what was the motivation?
On 2022-10-22 15:04:58 +0200, Peter J. Holzer wrote: > On 2022-10-19 12:10:52 +1100, Chris Angelico wrote: > > On Wed, 19 Oct 2022 at 12:01, Peter J. Holzer wrote: > > > On 2022-10-17 09:25:00 +0200, Karsten Hilbert wrote: > > > > http://literateprogramming.com/ > > > > > > Right. That's one of the inspirations for my comment. > > > > > > But literate programming is of course still very much rooted in the > > > "linear text representation" paradigm. You have one definite source > > > which is a linear text. > > > > > > In a world of IDEs, databases and hypertext that's probably not the best > > > we can do. As Raymond Hettinger would say, "there must be a better way". > > > > > > It would be very different from mainstream programming languages, > > > however. And ideally you would want it to integrate with a lot of other > > > infrastructure. So that alone might make it a non-starter, even if it > > > was really good (which realistically early iterations wouldn't be). > > > > There are special-purpose languages like Scratch which are not simple > > text in that form. > > Yes, I know. > > It has a different goal though: Scratch tries to establish a friendly > learning environment. Get rid of typing and syntax errors that beginners > find so frustrating. > > What I'm interested in is an enviroment for developing medium-sized real > applications. Somewhere in the several person-months to several > person-years of effort, hundreds of user-stories, maybe thousands of > bug-reports and change-requests over its life-time. [...] > And of course there have been lots of CASE tools over the years. A possibly totally different approach: There are tools[1] for authors which are supposed to help them keep all their characters, events, timelines, etc. in order. I have never used one (I don't plan to write a novel anytime soon), but what I've heard of them sounds like it would be useful for software-development, too. hp [1] E.g. Campfire (https://www.campfirewriting.com/) -- _ | Peter J. Holzer| Story must make more sense than reality. |_|_) || | | | h...@hjp.at |-- Charles Stross, "Creative writing __/ | http://www.hjp.at/ | challenge!" signature.asc Description: PGP signature -- https://mail.python.org/mailman/listinfo/python-list
Re: for -- else: what was the motivation?
On 2022-10-19 12:10:52 +1100, Chris Angelico wrote: > On Wed, 19 Oct 2022 at 12:01, Peter J. Holzer wrote: > > On 2022-10-17 09:25:00 +0200, Karsten Hilbert wrote: > > > http://literateprogramming.com/ > > > > Right. That's one of the inspirations for my comment. > > > > But literate programming is of course still very much rooted in the > > "linear text representation" paradigm. You have one definite source > > which is a linear text. > > > > In a world of IDEs, databases and hypertext that's probably not the best > > we can do. As Raymond Hettinger would say, "there must be a better way". > > > > It would be very different from mainstream programming languages, > > however. And ideally you would want it to integrate with a lot of other > > infrastructure. So that alone might make it a non-starter, even if it > > was really good (which realistically early iterations wouldn't be). > > There are special-purpose languages like Scratch which are not simple > text in that form. Yes, I know. It has a different goal though: Scratch tries to establish a friendly learning environment. Get rid of typing and syntax errors that beginners find so frustrating. What I'm interested in is an enviroment for developing medium-sized real applications. Somewhere in the several person-months to several person-years of effort, hundreds of user-stories, maybe thousands of bug-reports and change-requests over its life-time. The people using such a system/language would be professional programmers. They probably don't need much help to get the syntax of a for loop right. What they do need, though: * Cross-reference between requirements and code. (Yes, you can write comments, yes, you will hopefully have meaningful commit messages. Still, I see a lot of room for improvements there) * Cross-references between related parts of the code. (Yes, many IDEs can jump to the definition of an instance or list all instances of a definiton, But sometimes the relationship isn't that mechanic. And yes, you can use comments fpr that, too) * Views which highlight some parts of the code and omit others. (Folding editors do that in a very limited fashion) * For example, I might want to see only the code proper when I'm focusing on an algorithm or I might want to see lots of context (type definitions, requirements, test results, ...) * Classes often have quite a lot of methods with no natural order. Being able to view only a subset of them in some custom order may help. * Going back to the core idea of literate programming: Especially views which show some requirement(s) together with the code that implements them plus some explanation why that implementation was chosen. Presented like this, it's clear that the "language" (i.e. the file format) is probably the smallest part of the problem. How the user can view the program, how they can edit it, and how to keep the whole thing manageable is a much bigger question. And it would probably be a good idea to start at the system level and not at the language level. > My Twitch channel bot has a command executor whose language, if you > call it that, is basically JSON - and the way to edit those commands > is very Scratch-inspired. I designed a graphical filter language for database queries once. The idea was that you could combine various operations (selects, projections, grouping, transformations, ...) into pipelines via a web interface. We did implement it (sadly it wasn't me who did it), and it turned out to be a lot harder than I thought to make that actually usable. And of course there have been lots of CASE tools over the years. That seems to have been mostly a fad of 90s. Still, there were some good ideas there (although not alway implemented well), and something bubbles back up every now and then. hp -- _ | Peter J. Holzer| Story must make more sense than reality. |_|_) || | | | h...@hjp.at |-- Charles Stross, "Creative writing __/ | http://www.hjp.at/ | challenge!" signature.asc Description: PGP signature -- https://mail.python.org/mailman/listinfo/python-list
