You shoud seriously look at the napoleon / google doc: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/
This is already implemented and supported standard.
Yes indeed. For those unfamiliar, here are (from the link) examples of the two docstring styles that Napoleon (a Sphinx extension) parses and renders. PyCharm, too, parses Numpy and Google docstrings and uses the information for tooltips, static analysis, etc.
Google style:
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True
NumPy style:
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
"""
return True
Hmm, Google’s style + napoleon extension does seem quite good. I wonder if I should update my style guide. I suggested that you should just bite the bullet and use Sphinx style there due to the doc auto-gen benefits, but seems like this is best of both worlds.
In progress:
Recently finished:
Building E-commerce Applications, a complete waste of money and basically just a lazy compilation of undedited blog posts. Booooo.
Come and Take It: The Gun Printer’s Guide to Thinking Free, by Cody Wilson of Defense Distributed fame. I finished this probably a week before the current kerfluffle started. There’s a whoooole lot of self-congratulatory bullshit and bluster in this, as Wilson is first and foremost (in my opinion) an attention whore, but buried in there are a couple of good reflections on the role of toolmakers in the pursuit of independence.
Come as You Are, a delightful book by Emily Nagoski that I heard about through OhJoySexToy (webcomic about sexual health and practices). It covers a lot of interesting academic information about sex, attraction, and romance, and can help in debugging certain failure modes of relationships or in preemptively being a better partner.
buried in there are a couple of good reflections on the role of toolmakers in the pursuit of independence.
We cannot be free until we control the means of production? That sounds like a good reflection, all right :-)
(Note: this may sound like I’m trying to rile you. I’m not, I am genuinely amused to see Marx echoed in this unexpected context.)
As the good Chairman once said, “Political power grows out of the barrel of the gun…”.
A lot of Marxists, communists, and libertarians I think would actually have a lot to talk to each other about if they weren’t so busy engaging in culture war these days.
It isn’t too surprising, since all three sprang from the same philosophical tradition.
A funny aside: a friend of mine recently noted, with regard to economics, we’re all Marxists now.
Yup! Certain groups don’t really like to think about it, but because Marx did the first serious systematic analysis of how economies worked on a global scale (and coined the word “capitalism”, although contrary to popular opinion he did not coin but merely redefined “communism”), all modern economics owes a debt to Marx at least as big as the one it owes to Von Neumann. Even those opposed to Marx’s conclusions are using methods he pioneered to fight them. (Or, to be more direct: “economics begins with Marx” / “Karl Marx invented capitalism”)
You might like this recent podcast episode from BBC Thinking Allowed: Marx and Marxism: https://www.bbc.co.uk/programmes/b0b2kpm0
Come and Take It: The Gun Printer’s Guide to Thinking Free, by Cody Wilson of Defense Distributed fame. I finished this probably a week before the current kerfluffle started. There’s a whoooole lot of self-congratulatory bullshit and bluster in this, as Wilson is first and foremost (in my opinion) an attention whore, but buried in there are a couple of good reflections on the role of toolmakers in the pursuit of independence.
This was on my reading list; but, after I did the ’ol Amazon “Look Inside,” I took it off because it looked like the signal/noise would be unacceptable. Please give a shout if it ends up being worthwhile. I watched a few of his pre-DD/early-DD lectures on philosopy, and the guy gave me stuff to chew on.
So, again, having finished it I think the same points could be handled in a pamphlet instead of the drawn-out narrative Wilson attenpts.
Cody Wilson Philosophy, Part I is the first of a two part series.
Why I printed a gun is short and sweet; but, doesn’t get too deep.
I just finished Moby Dick today! It is a very good book, and I’d take it to with me to a desert island. Around the start and the end, where the foreshadowing is thickest, it reminded me a lot of Dracula – that’s the romantic influence, I suppose. It is also very funny in many places :-D
Mods, can I merge this (‘my’) submission with/into the submission that contains the official announcement? (I couldn’t find an official way to propose a merge, hence this comment.)
As usual with decentralized systems, the main problem I had was discovering good feeds. One could find stuff, if one knew what one was looking for, but most of the time these feeds only contain the first few lines of a article. And then again, there are other feeds that just post too much, making it impossible to keep up. Not everyone is coming to RSS/Atom which a precomposed list of pages and websites they read.
These are the “social standards”, which I belive are just as important as the technical standards, which should have to be clarified in a post like this one.
I agree. Finding good feeds is difficult indeed, but I believe that good content does spread by word at some point (it may even be word in social media, actually). Feeds that post too much are definitely a problem. Following RSS/Atom feeds of newspapers specifically defeats the purpose. Nobody can manage this hilarious amount of posts, often barely categorised. I don’t have a solution for these at hand; this article suggests that the standard should be improved on this. It might be a good idea to do so.
Excerpt feeds I don’t like, because they are hard to search using the feed reader’s search facilities. I however still prefer an excerpt feed over no feed at all, which is why the article mentions this as a possible compromise. The main reason for excerpt feeds appears to be to draw people into the site owner’s Google Analytics.
As far as unmanageably large&diverse sites go, I seem to recall at The Register you can/could run a search and then get an RSS feed for current and future results of that query. Combined with ways to filter on author etc. that worked a treat.
the main problem I had was discovering good feeds
This is why my killer feature (originally of GOOG Reader and now of NewsBlur) is a friends/sharing system. The value of shared content is deeply rooted in discovery of new feeds.
feeds only contain the first few lines of a article
Modern feed readers generally support making it easy to get full articles / stories without a context switch.
feeds that just post too much, making it impossible to keep up
Powerful filtration is also another place where modern readers have innovated. Would definitely check them out, because these are solved problems.
NewsBlur is pretty great. It’s a hosted service, rather than a local application, but that’s kind of necessary for the whole “sharing” thing.
If you’re an emacs user: elfeed. It has pretty good filtering and each website can be tagged.
I tried that for a while, but eventually I just couldn’t keep up. I never really have the time to read an article when I’m in Emacs, since usually I’m working on something.
I have been quite pleased with NewsBlur. It has the added benefit of being open source, so if it were to disappear (cough, cough, GOOG Reader), it could easily be resurrected.
For the social aspect, of course, might want to poll friends first to see what they are on.
The author is convincingly enthusiastic about Pop OS! My girlfriend thinks so, too; she’s making the boot USB as I write this.
The author does, however, come across as more of an interface rules zealot than an interface expert; at least, that’s what I get when he defends each of the App Menu’s problems as ‘actually the right thing’ or ‘we aren’t enforcing the rules strictly enough’, without reference to users’ lived experiences. I, too, like the App Menu in theory! It could work! But you have to make it work, not say it works.
Anyway, we’re going to try out Pop OS, this should be fun :-D
This is super fun, but the result isn’t surprising from a geometric point of view. The configuration space of n points in the plane (that is, all the possible pictures we can make with n points) is an algebraic manifold of dimension n!. Fixing the mean, median, correlation and some other parameters of those points only removes one degree of freedom for every property we fix. As n! is very large, and we only fix a handful of properties, we still have an enormous amount of space to move in and create images that are obviously completely different.
but the result isn’t surprising from a geometric point of view.
In this case I myself would go for the ‘did I see it coming’ definition of surprise, rather than ‘is it unlikely to occur’. Otherwise, no maths could ever be surprising, could it? I’m personally fond of the phrase ‘surprising yet inevitable’ – I got it from Howard Tayler talking about fiction writing, and apparently it was first said by Aristoteles, but it’s neat for this sort of thing, too.
Also, thanks for the n!-based explanation, that was new (and surprising!) to me.
For me, it was more a layperson view on it. I watch news articles post contradictory statistics all the time. They seem easy enough to massage to prove about any BS you want. That they can get different datasets to produce the same means or whatever is unsurprising from that perspective of “statistical results are easy to fake or mislead with if audience isn’t a statistics expert reviewing their methodology and data.”
The visualizations were still cool, though.
I recall him stating a tangential: that writing ruby libraries is a fairly unaesthetic tasks, but gives possibility of clean interfaces. Vice versa for py: lib’s code is nice, but the user interface sometimes leaves a lot to be desired.
So this is a really late reply, but you sparked a thought: this is exactly what is currently happening in R, with the recent Hadley-inspired flood of packages that use non-standard evaluation to deliver interfaces that are super nice for interactive use (because the function takes care of evaluating your arguments in the context of the dataset argument).
Heya, please don’t take my downvote personally! The article is completely general and not specifically tech-related, which is not a problem in itself; and it was written by you for your company, and that’s also not a problem in itself; but taken together that feels more like spam, hence my downvote.
A good litmus test, I think, is ‘would I also submit this article lobste.rs if I hadn’t written it, and I found it in the wild?’
P.s. I really enjoyed your article on Material Design. Thanks again for writing and posting that one!
Hey. I understand the reasons behind the downvote and that also helps me understand better what I should or shouldn’t post. I’ll take this feedback into account for future submissions.
Can someone explain to me how Apple gets away with a dictatorship on iOS without any lawsuits?
Apple controls the only app store allowed on iOS
Apple apps get access to features not available in third party apps
Third party apps aren’t allowed to compete with Apple apps in many instances and are banned from the store
All defaults are Apple apps, and in many cases can’t be changed to something else
As a consumer I felt less restricted when I’ve been on Google’s platform than when I’ve been on Apple’s. I don’t have any horse in this race, I’m just curious how Apple has managed to avoid scrutiny. I’ve switched back and forth am currently using an iPhone 6S that I’ve had for over 3 years.
This is not about Android, but about the Google Search monopoly. If you feel like it, read the announcement: it’s amazingly clear writing, a joy to read.
Excerpt, emphasis added:
The Commission decision concerns three specific types of contractual restrictions that Google has imposed on device manufacturers and mobile network operators. These have enabled Google to use Android as a vehicle to cement the dominance of its search engine. In other words, the Commission decision does not question the open source model or the Android operating system as such.
There are a couple of obvious things:
Aside from that, I suppose platform restrictions don’t get classified as monopolistic behaviour.
Is it really just a marketshare thing? The iOS lockdown seems a lot more insidious than Microsoft’s IE bundling, for example. If it was iOS that had a 80%+ marketshare would Apple be the ones targeted?
Not necessarily - it seems there are specific criteria for what constitutes abuse of a dominant market position. The issue that caused the fine is that Google is abusing its position in search:
Google has used Android as a vehicle to cement the dominance of its search engine. These practices have denied rivals the chance to innovate and compete on the merits. They have denied European consumers the benefits of effective competition in the important mobile sphere. This is illegal under EU antitrust rules.
In particular, Google:
- has required manufacturers to pre-install the Google Search app and browser app (Chrome), as a condition for licensing Google’s app store (the Play Store);
- made payments to certain large manufacturers and mobile network operators on condition that they exclusively pre-installed the Google Search app on their devices; and
- has prevented manufacturers wishing to pre-install Google apps from selling even a single smart mobile device running on alternative versions of Android that were not approved by Google (so-called “Android forks”).
So this is a programming class aimed specifically at seniors? That sounds like a lot of fun. If it’s not an impertinent question, what sort of work/lives/hobbies did you and your classmates have before you retired / what prompted you all to get into programming?
Thanks! We had a good laugh at your comment. I don’t think the post mentions school until the very end, so it’s pretty reasonable!
You’re right, that’s an odd choice by the 6(!) flaggers. The article seems fine to me, too. Unless I, too, am missing something.
I’ll come back later and edit this comment with links; but if this is a suitable replacement for the defunct cheat.errtheblog.com gem, I shall be very happy indeed.
Too late to edit, so here’s a reply, instead. Re: the cheat gem:
gem install --user cheat; cheat cheat, and away you go. Some features don’t work, though: cheat sheets and cheat recent to show all (recent) sheets both get 404 errors.cheat --edit sadly does not currently work. The --edit option was the best thing about the cheat gem: it was a command-line wiki, not a lookup tool.Re: cheat.sh:
/:learn returns the relevant https://learnxinyminutes.com lesson, for example.cht.sh python/:list returned a short list of entries, including doc, that suggested that, but the servers overloaded before I could check cht.sh python/doc/:list. My experience with wikis both flat and nested has led me to strongly prefer flat namespaces over nested ones for general reference works, but good search covers a multitude of sins.I had some fun last week creating a small interactive checklist program with a curses interface, which I gave an Elm-style architecture. Only thing is: curses can only create interfaces that take over the entire terminal screen. I’d quite like the checklist to take only as many lines as it needs, and to remain visible like any other program output when I exit.
If I feel like it this week, I might look into creating a takes-up-only-a-few-lines TUI using prompt_toolkit. On the other hand, I might bypass prompt_toolkit and figure out which VT100 codes to send. One, the other, or something else, as my whimsy takes me.
My long-term thing I’d quite like to do, by the way, is to create GTK or Qt programs for the desktop; but every library I’ve found so far has been unappetizingly imperative in style. If anybody knows a desktop GUI framework they’d like to recommend (especially if it’s Elm-like!), my ears are open.
Opera 12.16 renders it the same as Edge, which is the rendering that Martijn called ‘probably correct’, so, yay! On the other hand, Codepen’s ‘Local revisions’ notification sidebar was permanently visible, which could be a missing CSS feature in Opera 12 – it’s from 2013, after all.
Also, I had forgotten how amazingly snappy Opera 12 was to use. I miss it. It’s going to become to browsers what WordPerfect 5.2 is to word processor nostalgia, isn’t it?
Surprisingly, ‘completely’ is not even an exaggeration — the front-end, too, is written in Rust, using the Yew library (lobste.rs thread), which compiles to wasm to run in the browser and render the DOM . Nice!
I also like the fact that Yew is Elm+React-inspired. The Elm architecture is fantastic to work with. Neat detail, though: where Elm attacks shared mutable state by making the state objects shared but immutable (state + events -> new state), in Yew the state is mutable but unshared (Rust prevents writing code that would cause simultaneous updates.)
All of the above written without having used Yew myself, only some Elm and hardly any Rust, so please add grains of salt as required.
That was also my number one takeaway from the article. I knew about compiling to WASM targets but had no idea the front end story included full frameworks like Yew.
This alternative title turned up in my brain and won’t let go, so I’m writing it here to get it out of my head:
You don’t need ML/AI. You need data queries and business logic.
I’m not trying to argue with the original title! SQL is definitely the right language for querying data and gathering cases to feed to the business logic. Also, it is a well-written article that makes its case for the use of queries and business logic very nicely. Thanks for sharing it!
You don’t need ML/AI. You need data queries and business logic.
I think that hits on an important point that the article misses (or sidesteps): business logic. SQL is only helpful if you can describe what you’re looking for, and doing that requires knowledge and skill.
When you lack the ability to describe what you’re looking for, then SQL seems useless, and ML seems magically useful. Of course, you’ll still end up doing that work if you opt for an ML approach, it will just be less obvious.
(digression: this parallels the problem of not being able to describe what you’re storing, which leads to poor usage of NoSQL databases)
Now, if you have a broad notion of what you’re looking for, and a willingness to experiment, then ML (well, analysis of any kind) can help. What about the contents of a basket can be a predictor for returning after a reminder email? What is the right size of a coupon to entice people back while minimizing cost? What is the right period of time to contact someone after an absence? More customers/transactions/views/baskets means more leeway to experiment, which means more data, which means more use cases for an ML-style approach.
But, yes, absolutely, simple querying will be a better ROI until you get hyuuge.
When you lack the ability to describe what you’re looking for, then SQL seems useless, and ML seems magically useful.
From the point of view of SQL, I would state this as “when you lack the ability to describe your relationships.” Whether you know enough in advance to add table constraints or write queries to discover them, SQL helps (forces) you to make your data categorically consistent.
Nice writeup! I like the way that you link to relevant code sections instead of including code in the document – it made my brain ‘switch modes’ and pay more attention to the code, instead of skimskipping it as I often do with interleaved snippets.
I only did that because medum’s support for inline code is awful. (It stripped newlines and replaced them with 80 spaces, for some reason…) I’m glad it worked out, though :)
Teaching children programming so they understand stuff doesn’t happen ‘because magic’, and to expose them to things they might like, are indeed good reasons.
Our lives are shaped by governmental, societal, and/or bureaucratic systems surrounding us, and we have learned civics so that we may understand how these systems work, how we may expect them to behave, and what our points of entry are to engage with them, help shape them, and even (though this is seldom taught explicitly) resist them. These reasons for teaching civics, I believe, also hold for teaching programming.
To an ever greater extent, our lives are also surrounded and shaped by programmed systems. By teaching programming and other parts of IT, we can give people a mental model of programs (including websites); help them understand what failure modes programs have, and how to work around that; teach how programs enforce their programmers’ ideas of success, and how to work around that; and teach them what points of entries they have to engage with existing programs and their owners, help shape them, and resist them. It would be terrible to teach our students how to actively engage with the non-automated parts of society, but not with the automated parts.
Just makes me wonder how many people use mercurial at there company?
Edit: from company I mean at work.
Which company? Octobus? As per their website, there are only 2 people, and Pierre-Yves David (“marmoute”) is a well know core Mercurial contributor. The company itself is about providing commercial support for Mercurial, along with other stuff like Python contracting.
I think mercurial definitely has a niche in a corporate space. It’s easier to train new people on than git, scales better for monorepo setups, is more easily extensivle via python, and allows richer customization.
I am curious about this – while mercurial definitely has less initial surface area and a far more consistent way of interacting. It also tends to have lots of customizations that add a lot of complexity right back in – and mix and match them in ways that are often unique per mercurial setup.
Git while far uglier, also has more training resources both professional and free. Additionally, while git is far less consistent in terms of interaction, to a far large degree once you know it – you know it. You are unlikely to go to a site where git has lots of customizations making it behave different than the “git” you used at your last organization.
Well you pretty much summed it up :) Mercurial is nicer/easier to use, but Git has more resources out there. I think at that point one being better than the other for a particular person or team will then depend less on the pros/cons of each tool, and more on the person/team’s mindset/culture/available support/etc.
I’d add that Git having more resources, while helpful, is as much a proof of its success as a symptom of one of its main problems. Having to look up help pages and other tutorial pages on a regular basis becomes tedious quickly, and they still need to fix the core problem (they can’t quite fix the broken CLI at this point, but I did note several helpful messages being added to the output in the last few versions, so there’s progress).
Finally, yeah Mercurial has a problem with the amount of customization they force on user because of their very strict backwards compatibility guarantees (resulting in a good portion of new features being turned off by default). This tends to be mitigated by the fact that teams will generally provide a central
.hgrcthat sets up good defaults for their codebase. Also, Mercurial extensions almost never change Mercurial’s behaviour (evolveis an outlier there but is still considered “experimental”) – they just add to it, so I’ve never come across (so far) any Mercurial resource that was potentially invalidated by an extension (feel free to point to counter-examples!).I suspect my issue might be more in my head (and my unique experience) than in reality. I have contracted with lots of git shops – and a fair number of mercurial ones. Most of the git shops worked very similarly, they differed in master dev versus feature branch dev, mono-repo or multi-repo – but they all felt similar and I could use very minor changes to my workflow to integrate with them, which is great for contracting.
Each mercurial shop has been a wild adventure in unique workflow, and brand new extensions I have never seen or used. One used TWO different sub-repo extensions, another one used THREE configuration extensions! On top of that, most of them had annoying/wonky authentication mechanisms (some hand-rolled). The reason I use those examples (which is only a fraction of what I have seen) is that are all basically non-optional. I needed to use them to be able to work on the project… and of course mq versus non-mq. Never used evolve (yet).
During the “will mercurial or git win?” – I was firmly on the mercurial side because I did work on Windows and git early on was non-function on it. But now when I hear a client is a mercurial shop, I dread it. But, I realize that is probably just my unique experience.
Huh, well it’s very probable I’m just not aware of all the wild things people do out there with Mercurial. I frankly had no idea there were sub-repo extensions (outside of the core subrepo feature), and I don’t know why anybody would do custom authentication when SSH works everywhere (although I understand people might want to setup ActiveDirectory for Windows-only environments instead, but that’s it). What do you mean by “configuration extensions”? As for MQ, I don’t think it matters for the central repo, no? It should only matter for local workflows?
According to https://www.mercurial-scm.org/wiki/UsingExtensions – there are at least 6 sub-repo extensions. And, yes, ActiveDirectory logins, other SSO variations and then on top of those multiple ACL layers.
As for MQ – absolutely you can avoid it with others tools that can produce the same sort of history… rebase, graft, strip, etc. The issue being if all the “how we work” docs are written in MQ style – it is a bit of mental gymnastics to convert over.
Ah I see. And yeah I never really scrolled down past the non-core extensions :) (The only non-core extensions I have are a couple I wrote myself…)
you… you are part of the problem! runs scared hehe
Haha but that’s fine, I don’t think anybody besides myself are using them :)
Might it instead be the other way around: that customization-seeking companies are more likely to choose Mercurial? This could be either because adventurousness promotes both non-Git and customization, or because Mercurial has the better architecture when you need to customize. IIRC the latter is true for both Mozilla and Facebook. Anyway, at my second job we used vanilla Mercurial, and we did fine. It was basically the same as any Git workflow, for that matter.
Absolutely. Additionally, Mercurial is just more accessible in terms of customization. On top of that more than a handful of these shops had heavy Python contingents internally.
Haha, yes, knowing the language certainly makes it easier to stray off the common path and into the woods of in-shop customization :-D
I use Mercurial at work. My company uses Git, but I use Mercurial and clone, push, and pull transparently thanks to hg-git. I’ve noticed I am generally more aware than my Git-using colleagues of recent changes to the repo, because I’ve got a
pre-pullhook set up to runhg incoming(with a tweak to avoid double network talk).