I use Obsidian daily as a journal system, a knowledge base, and writing tool. But also as a record of what AI coding agents are doing. I don’t always offload work to AI, but when I do, I prefer accountability. So here’s my setup:
Keep a reliable folder hierarchy in Obsidian for projects. I have /Project Notes/<ProjectName> as my scheme.
Within it, have an AI Notes folder.
Add the following to AGENTS.md or CLAUDE.md:
* Keep a record of any approved plans in the form of ``YYYYMMDD-HHMM - Summary.md`` under an `AI Plans` directory under the relevant project directory in`/Users/chipx86/Documents/Obsidian/Main/Project Notes`. Search for the project name under here (it may be nested) and, if not found, suggest a name relative to this and let me correct you if needed. You may create directories within here.* If there's any particularly interesting tips or concepts that are discovered during development, record them. If this is specific to a project, file it in a`Project Tips` directory under the corresponding `Project Notes` directory. If instead it's more general to programming (not-project-specific), write them to`/Users/chipx86/Documents/Obsidian/Main/Today I Learned/AI Drafts` (named in`YYYYMMDD - Summary.md` format). Not every change warrants this, only if it's noteworthy. You may ask me if there's any doubt.* For any records living in Obsidian, use Obsidian Frontmatter to specify the date and tags at the top of the file:```markdown---date: YYYY-MM-DDtags: - "..." - "..."---``` Fill out as appropriate. For plans, use the `AIPlan` tag. For interesting notes, use the `til` tag.
(Claude Code usually respects this. Though sometimes I do have to give it a nudge. Always check!)
Keep in mind, coding agents do their job and then forget. And we can easily forget along with them. They don’t think about their work after the fact and they don’t take showers. So keeping records and receipts of their work can be incredibly helpful when going back to a change and wondering, “what the hell was it thinking?”
Code review is important, maybe more important than ever, but inherently focuses on the end result. We’ve long done Image Review and Document Review, which is also not Code Review. And now that development is changing, as AI takes on more of the process, review needs to involve the work items AI will pick up, any planning or assets that precede the change, and any weigh-in from other people or agents involved in the project.
So we’re rethinking Review Board’s role as more an end-to-end Review-Driven Development tool.
Not just code review, but the review of the high level and the nitty-gritty. The staging of the work and the end result. The things that keep teams able to collaborate and build a product without it going off the rails in siloed one-off Claude or Codex sessions.
This is the Mission Control feature we’re building right now for Review Board 10.
And like everything we do, this will focus on on-prem, privacy, security, and work with existing tooling (rather than yet another walled garden dev ecosystem).
Planning to talk more about this as we get closer to having something to show.
I feel like the world of code review has somewhat stagnated. Most people use a variation on GitHub Pull Requests, which slowly began to catch up to the kinds of features we have in Review Board, but never quite got there. Good enough for many, but could be better for most.
In a similar vein, the world of code review has stagnated in what and where people can review. You pretty much have to be on a bespoke Git-based service, which leaves out companies with decades of history backed on Subversion, Perforce, and others. And you’re limited to just reviewing source code, when there’s so much more that goes into a product.
We built Review Board at a time before pull requests and the prevalence of Git, a time when code review was barely a thought in the minds of most software developers. As the concepts we worked to pioneer began to take hold, and more solutions entered the market, we watched them begin to coalesce around an overly-simple model that left little room for the non-code assets that comprise so many projects. We watched as cloud-based solutions began to dominate and on-prem got left behind along with all those legacy customers.
And now we’re watching the older waves of on-prem solutions begin to disappear, leaving customers stuck. Watching the rise of AI-focused and AI-only solutions threaten further slop in projects, with minimal human oversight.
And with all this, whole industries of creators are still being passed over.
We’re building better solutions
We have a few major things in the works for Review Board I’m so happy to begin talking about:
AI functionality is coming, and we’re building it with humans in mind. We believe in building stronger engineering teams instead of replacing them with AI. I’ll be talking about what’s coming as we get closer to launch, but this isn’t just another “throw code at the AI and hope its feedback is worth it.”
EDA Design is a major new feature we’ve got in the prototype phase. It allows designs for schematics and PCBs to be viewed, analyzed, and diffed across revisions. We announced that today for anyone interesting in signing up for a beta.
Crucible Import is also in progress. For decades, many industries depended on Crucible for their development, but in 2028 Crucible will be dead. Review Board is a good, modern fit for Crucible users, and we’re making it easy to import your history and pick up where you left off. There’s no need to move away from Perforce, Subversion, or whatever else you’ve got, but at the same time you can begin to review code hosted on GitHub, GitLab, Jujutsu, or others. Crucible users can sign up for a beta.
And we’re staying on-prem. Others want to bring you into their fold so they can own your whole environment. We believe in the portability and choice of tools, on-prem or in the cloud, and are holding firm on that.
I’ve written a lot of code over the past 35 years.
In my earlier years (starting at age 7), everything was an experiment, with nothing slated for production (thank god). I didn’t know the limits, I didn’t know design, and I didn’t know what I didn’t know. It was chaotic and glorious.
In my teens, responsibility began to kick in. I found myself in the world of Linux development, working on GNOME and Gaim/Pidgin, and later creating libnotify/notification-daemon, Galago, and others. So much of what I built was suddenly used by people and companies around the world. If I had an idea — a new function, a new feature — and saw it through, it’d be on people’s systems, part of people’s toolkits, part of my maintenance burden.
Early in my professional career, a friend and co-worker gave me piece of advice that stuck with me:
Don’t build what you don’t know you need.
If you only think you or your users will need that function or that interface someday, but there’s no evidence of it yet, maybe leave it out.
I grappled with this for a while, and initially pushed back against the idea (“BUT WHAT IF IT’S USEFUL!”, I’d think), but… he was right. And it ultimately shaped how I developed software, though with one tweak:
Don’t ship what you don’t know you need.
There’s value in the building, but that doesn’t mean everything you build must make it into the codebase.
I let this guide me when working on Review Board and other projects. It’s easy to go down a rabbit hole and want to fully flesh out some piece of architecture to its extremes or build some cool what-if feature, because it’s fun to write code! But more and more, I instead find myself choosing to leave that code behind and out of my final commit or review request.
It’s good to build, though. Exploring a concept, finding the extents of it, really understanding the problem space. But, if you trim it down to its best parts, you’ll often end up with something far more maintainable, more reviewable, more ready to build upon in the future.
Think about photography (do you dabble? I do). You might take a hundred pictures of a sunset and show just one or two. The stars of your work, the best of the best. All those pictures contributed to finding the ones you most want the world to see, but once you’ve done that, you can shelve those photos or toss them out.
Those pictures — and that code — may still be worth looking at in the future, worth revisiting. But it doesn’t need to be part of what you present, right now.
To put it simply, aim for quality over quantity, and know what to leave on the cutting room floor.
Let’s go over a neat thing I learned about this week.
We all know binary counting. It’s natural, we’re introduced to it around age 1 or 2, it’s delicious, and… no wait, I’m thinking about ice cream.
Focus, Christian.
Okay, so binary counting looks like this:
0 = 0001 = 0012 = 0103 = 0114 = 1005 = 101
Something you might notice is that often times you end up flipping multiple bits at once. Let’s look at the numbers 3 and 4:
3 = 0114 = 100
We flip all 3 bits when incrementing between 3 and 4.
That’s usually not an issue, but if they can’t all be flipped at exactly the same time (say, some mechanical operation is involved and there’s the slightest of delays between each flip), you could end up with these in-between numbers that aren’t what you’d expect.
Say the bits get flipped one-by-one, left to right:
3 = 011 111 // 7! 110 // 6!4 = 100
We got the garbage numbers 7 and 6 while trying to go from 3 to 4. That’s probably not great.
A solution to this is to flip only one bit when going between two numbers. And an approach to this is Gray code or “reflected binary code”. This is an alternative binary system where each number only differs by a single bit, making the above situation impossible:
Since there’s only ever one bit change at a time, you never risk getting a garbage value while flipping bits. Bit changes don’t have to be atomic.
There’s a few places where you may find Gray Code encodings:
Rotary encoders
Analog-to-Digital signal conversion
Position sensors
Error correction during communication
Some genetic algorithms
I just got those from the Gray code Wikipedia page. This has tons of examples and variations and so many diagrams and animations. You can tell that the editors were really interested in this subject.
It’s pretty easy to go between decimal numbers and Gray code. Just a bit of math:
I enjoy my morning routine. Get up, wake to the world through the phone, nibble on some breakfast, and sit down at the computer. I like to remind my sleepy brain what I was working on the night before, skim through my notes, get all that mental context ready for the day.
Then I take a shower and let the stream of water ease my mind into a calm, zen-like state, free to let the thinkless thoughts flow.
That’s usually when a brilliant idea will pop into my head. Or when I realize what I did wrong last night. Or when I come up with a better way forward.
If not in the shower, maybe it happens in my late-night slumber, solutions through a mess of vivid dreams. But whether dreamland or my morning shower, this is when important insights usually come to me.
Insights that depend on the depth of my work, the mental context I’ve developed working through the nuances. Insights that come from letting my brain sit with the problem, exploring it while I’m off doing other things. Insights that come to me in the shower.
Now, AIs are a powerful tool. They can achieve wonders. They can write code faster than I can. They can explore concepts in a fraction of the time and teach them to me. They can catch what I might miss. They can even rewrite my codebase from Python to Go and back.
But AIs don’t take showers.
They don’t sit and think about the problem after the code has been written. They don’t wake up at 3AM with a sudden realization. They don’t debate with themselves over the what-ifs and maybe-if-I’s. They don’t have a conversation over coffee or a read through a thread that sparks a sudden “ohhhh!” moment.
Their human could do all that. But their human hasn’t spent time with the code the way the AI did, didn’t internalize the decisions, weigh the trade-offs. Their human won’t know the code as well as the AI did in the moments it was writing it, just hours ago.
The code the AI has since forgotten.
That code now simply exists, a relic of a process, waiting to be learned all over again by people who didn’t write it. There’s nobody left who remembers the hundreds of tiny decisions that led to the way it is now. Nobody who struggled and theorized and debated their way to something finally ready for review. Nobody to call up and ask why it was done this way and not that way.
The great cognitive debt fallout felt from every layoff, now applied to every code change in the product.
Python offers a handy module called pprint, which has helpers for formatting and printing data in a nicely-formatted way. If you haven’t used this, you should definitely explore it!
Most people will reach for this module when using pprint.pprint() (aka pprint.pp()) or pprint.pformat(), but one under-appreciated method is pprint.saferepr(), which advertises itself as returning a string representation of an object that is safe from some recursion issues. They demonstrate this as:
>>>import pprint>>> stuff =['spam','eggs','lumberjack','knights','ni']>>> stuff.insert(0, stuff)>>> pprint.saferepr(stuff)"[<Recursion on list with id=4370731904>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
But actually repr() handles this specific case just fine:
Pretty minimal difference there. Is there another reason we might care about saferepr()?
Dictionary string comparisons!
saferepr() first sets up the pprint pretty-printing machinery, meaning it takes care of things like sorting keys in dictionaries.
This is great! This is really handy when writing unit tests that need to compare, say, logging of data.
See, modern versions of CPython 3 will preserve insertion order of keys into dictionaries, which can be nice but aren’t always great for comparison purposes. If you’re writing a unit test, you probably want to feel confident about the string you’re comparing against.
Let’s take a look at repr() vs. saferepr() with a basic dictionary.
A nice, stable order. Now we don’t have to worry about a unit test breaking on different versions or implementations or with different logic.
saferepr() will disable some of pprint()`’s typical output limitations. There’s no max dictionary depth. There’s no max line width. You just get a nice, normalized string of data for comparison purposes.
But not for sets…
Okay, it’s not perfect. Sets will still use their standard representation (which seems to be iteration order), and this might be surprising given how dictionaries are handled.
Interestingly, pprint() and pformat()will sort keys if it needs to break them across multiple lines, but otherwise, nope.
With this, you can set a style or a CSS variable based on some condition, like whether the device is on a touchscreen, or whether some CSS property is supported, or even based on an attribute on an element.
It’s really cool, and sooner or later we’ll all be (ab)using it.
Actually, you can pretty much do this today using CSS Variables, with a little understanding of how variable fallbacks work and how you can use this to make your own conditionals.
What are CSS Variables?
CSS Variables make it easy to use reuse colors and styles across a CSS codebase. At their most basic, they look like this:
CSS Variables can have fallbacks, which falls back to some other value if the variable isn’t defined. Here, the color will be black if --my-custom-fg-color wasn’t defined in the scope.
body {color:var(--my-custom-fg-color,black);}
This can be nested with other CSS variables:
body {color:var(--my-custom-fg-color,var(--my-fg-color,black));}
Fallbacks depend on whether the variable is truthy or falsy.
Truthy and Falsy Variables
When a variable is falsy, var() will use the fallback value.
When it is truthy, the fallback value won’t be used.
Normally, it’s falsy if the variable isn’t defined, and truthy if it is. But there are a couple tricks to know about:
You can make a variable falsy by setting it to the special keyword initial.
You can make a variable truthy (without expanding to a value) by making the value empty.
Let me show you what I mean:
:root {/* Empty -- Truthy and a no-op */ --no-fallback:;/* 'initial' -- Falsy, use fallback */ --use-fallback:initial;}body {background:var(--no-fallback,grey);color:var(--use-fallback,blue);}
This will result in the following CSS:
body {background:;/* No value -- ignored. */color:blue;}
Our new --use-fallback will ensure the fallback value will be used, and --no-fallback will ensure it’s never used (but won’t leave behind a value).
These are our core building blocks for conditional CSS Variables.
We can then combine these rules.
body {background:var(--no-fallback,red)var(--use-fallback,pink);color:var(--no-fallback,pink)var(--use-fallback,red);}
This will give us:
body {background:pink;color:red;}
Behold:
You can play around with it here:
Armed with this knowledge, we can now start setting CSS Variables based on other state, and trigger the conditions.
Setting Conditional Variables
Let’s set up another contrived example. We’re going to put together some HTML with a button that styles differently based on where it’s placed. In this case, when in <main>, it will appear blue-on-pink and elsewhere it’ll appear pink-on-blue.
It’s my post and I will use hideous color palettes if I want to.
We’re going to set up some conditional state variables based on the main placement. (Yep, contrived example, but this is just for demonstration purposes.)
But now we can’t give users a nice toggle on the page to control their light/dark modes, so we’ll want to bring the CSS classes back with the media selectors:
Now let’s use all that to style <body> and <button>:
body {background:var(--if-light,orange)var(--if-dark,darkorange);color:var(--if-light,darkgreen)var(--if-dark,blue);}button {background:var(--if-light,pink)var(--if-dark,blue);color:var(--if-light,blue)var(--if-dark,pink);}
Look at that. So much simpler to maintain. And we can extend that too, if we want to add high-constrast mode or something.
Let’s test it.
Here it is when we switch our system to dark mode:
Far less eye strain than light. I’m sold.
Now light mode:
And system dark mode with <html class="is-light"> overriding to light mode.
And system light mode with <html class="is-dark"> overriding to dark mode.
Perfection.
You can play with that one here:
Nesting Conditionals!
That’s right, you can nest them! Let’s update our Light/Dark Mode example to make a prettier color scheme, because I’m starting to realize what we had was kind of ugly.
We’ll define new --if-pretty and --if-ugly states to go along with --if-dark and --if-light:
And now we can build some truly beautiful styling, using nested conditionals:
body {background:var(--if-pretty,var(--if-light,linear-gradient( in hsl longer hue45deg,red0100%) ) )var(--if-dark,blacklinear-gradient( in hsl longer hue45deg,rgba(255,0,0,20%) 0100%) ) ) ) var(--if-ugly, var(--if-light, orange) var(--if-dark, darkorange) );color:var(--if-pretty,var(--if-light,black)var(--if-dark,white) )var(--if-ugly,var(--if-light,darkgreen)var(--if-dark,blue) );font-size:100%;}button {background:var(--if-pretty,radial-gradient(ellipseattop,orange,transparent ),radial-gradient(ellipseatbottom,orange,transparent ) )var(--if-ugly,var(--if-light,pink)var(--if-dark,blue) );color:var(--if-pretty,black)var(--if-ugly,var(--if-light,blue)var(--if-dark,pink) );}
In standard Ugly Mode, this looks the same as before, but when we apply Pretty Mode with Light Mode, we get:
And then with Dark Mode:
I am available for design consulting work on a first-come, first-serve basis only.
Here it is so you can enjoy it yourself:
A Backport from If()
Google’s article on if() has a neat demo showing how you can style some cards based on the value of a data-status= attribute. Based on whether the value is pending, complete, or anything else, the cards will be placed in different columns and have different background and border colors.
Here’s the card:
<divclass="card"data-status="complete"> ...</div>
Here’s how you’d do that with if() (from their demo):
You can use this today in all browsers that support CSS Variables. That’s.. counts.. years worth of browsers.
It requires a bit more work to set up the variables, but the nice thing is, once you’ve done that, the rest is highly maintainable. And usage is close enough to that of if() that you can more easily transition once support is widespread.
We’ve based Ink, our (still very young) CSS component library we use for Review Board, around this conditionals pattern. It’s helped us to support light and dark modes along with the beginnings of low- and high-contrast modes and state for some components without tearing our hair out.
Give it a try, play with the demos, and see if it’s a good fit for your codebase. Begin taking advantage of what if() has to offer today, so you can more easily port tomorrow.
I’ve been doing some work on Review Board and our utility library Typelets, and thought I’d share some of the intricacies of function signatures and their typing in Python.
We have some pretty neat Python typing utilities in the works to help a function inherit another function’s types in their own *args and **kwargs without rewriting a TypedDict. Useful for functions that need to forward arguments to another function. I’ll talk more about that later, but understanding how it works first requires understanding a bit about how Python sees functions.
Function signatures
Python’s inspect module is full of goodies for analyzing objects and code, and today we’ll explore the inspect.signature() function.
inspect.signature() is used to introspect the signature of another function, showing its parameters, default values, type annotations, and more. It can also aid IDEs in understanding a function signature. If a function has __signature__ defined, it will reference this (at least in CPython), and this gives highly-dynamic code the ability to patch signatures at runtime. (If you’re curious, here’s exactly how it works).
There are a few places where knowing the signature can be useful, such as:
Automatically-crafting documentation (Sphinx does this)
Checking if a callback handler accepts the right arguments
Checking if an implementation of an interface is using deprecated function signatures
Let’s set up a function and take a look at its signature.
If you guessed it wouldn’t have cls, you’d be right.
Only unbound methods (definitions of methods on a class) will have a self parameter in the signature. Bound methods (callable methods bound to an instance of a class) and classmethods (callable methods bound to a class) don’t. And this makes sense, if you think about it, because this signature represents what the call accepts, not what the code defining the method looks like.
You don’t pass a self when calling a method on an object, or a cls when calling a classmethod, so it doesn’t appear in the function signature. But did you know that you can call an unbound method if you provide an object as the self parameter? Watch this:
In this case, the unbound method MyClass.my_method has a self argument in its signature, meaning it takes it in a call. So, we can just pass in an instance. There aren’t a lot of cases where you’d want to go this route, but it’s helpful to know how this works.
What are bound and unbound methods?
I briefly touched upon this, but:
Unbound methods are just functions. Functions that are defined on a class.
Bound methods are a function where the very first argument (self or cls) is bound to a value.
>>>defmy_func(self):...print('I am',self)...>>>classMyClass:.........>>> obj =MyClass()>>> method = my_func.__get__(MyClass)>>> method<bound method my_func of <__main__.MyClass object at 0x100ea20d0>>>>> method.__self__<__main__.MyClass object at 0x100ea20d0>>>> inspect.ismethod(method)True>>>method()I am <__main__.MyClass object at 0x100ea20d0>
my_func wasn’t even defined on a class, and yet we could still make it a bound method tied to an instance of MyClass.
You can think of a bound method as a convenience over having to pass in an object as the first parameter every time you want to call the function. As we saw above, we can do exactly that, if we pass it to the unbound method, but binding saves us from doing this every time.
You’ll probably never need to do this trick yourself, but it’s helpful to know how it all ties together.
By the way, @staticmethod is a way of telling Python to never make an unbound method into a bound method when instantiating the object (it stays a function), and @classmethod is a way of telling Python to bind it immediately to the class it’s defined on (and not rebind when instantiating an object from the class).
How do you tell them apart?
If you have a function, and you don’t know if it’s a standard function, a classmethod, a bound method, or an unbound method, how can you tell?
Bound methods have a __self__ attribute pointing to the parent object (and inspect.ismethod() will be True).
Classmethods have a __self__ attribute pointing to the parent class (and inspect.ismethod() will be True).
They might have a self or cls parameter in the signature, but they might not have those names (and other functions may define them).
They should have a . in its __qualname__ attribute. This is a full .-based path to the method, relative to the module.
Splitting __qualname__, the last component would be the name. The previous component won’t be <locals> (but if <locals> is found, you’re going to have trouble getting to the method).
If the full path is resolvable, the parent component should be a class (but it might not be).
You could… resolve the parent module to a file and walk its AST and find the class and method based on __qualname__. But this is expensive and probably a bad idea for most cases.
Standard functions are the fallback.
Since unbound methods are standard functions that are just defined on a class, it’s difficult to really tell the difference. You’d have to rely on heuristics and know you won’t always get a definitive answer.
(Interesting note: In Python 2, unbound methods were special kinds of functions with a __self__ that pointed to the class they were defined on, so you could easily tell!)
This is very simplistic, and can’t be used to represent positional-only arguments, keyword-only arguments, default arguments, *args, or **kwargs. For that, you can define a Protocol with __call__:
from typing import ProtocolclassMyCallback(Protocol):def__call__(self,# This won't be part of the function signaturea:int,b:str,/,c: dict[str,str]|None,*,d:bool=False,**kwargs,)->str:...
Type checkers will then treat this as a Callable, effectively. If we take my_func from the top of this post, we can assign to it:
cb: MyCallback = my_func # This works
What if we want to assign a method from a class? Let’s try bound and unbound.
classMyClass:defmy_func(self,a:int,b:str,/,c: dict[str,str]|None,*,d:bool=False,**kwargs,)->str:return'42'cb2: MyCallback = MyClass.my_func # This failscb3: MyCallback =MyClass().my_func # This works
What happened? It’s that self again. Remember, the unbound method has self in the signature, and the bound method does not.
Let’s add self and try again.
classMyCallback(Protocol):def__call__(_proto_self,# This won't be part of the function signatureself: Any,a:int,b:str,/,c: dict[str,str]|None,*,d:bool=False,**kwargs,)->str:...cb2: MyCallback = MyClass.my_func # This workscb3: MyCallback =MyClass().my_func # This fails
What happened this time?! Well, now we’ve matched the unbound signature with self, but not the bound signature without it.
Solving this gets… verbose. We can create two versions of this: Unbound, and Bound (or plain function, or classmethod):
classMyUnboundCallback(Protocol):def__call__(_proto_self,# This won't be part of the function signatureself: Any,a:int,b:str,/,c: dict[str,str]|None,*,d:bool=False,**kwargs,)->str:...classMyCallback(Protocol):def__call__(_proto_self,# This won't be part of the function signaturea:int,b:str,/,c: dict[str,str]|None,*,d:bool=False,**kwargs,)->str:...# These workcb4: MyCallback = my_funccb5: MyCallback =MyClass().my_func# These fail correctlycb7: MyUnboundCallback = my_funccb8: MyUnboundCallback =MyClass().my_funccb9: MyCallback = MyClass.my_func
This means we can use union types (MyUnboundCallback | MyCallback) to cover our bases.
It’s not flawless. Depending on how you’ve typed your signature, and the signature of the function you’re setting, you might not get the behavior you want or expect. As an example, any method with a leading self-like parameter (basically any parameter coming before your defined signature) will type as MyUnboundCallback, because it might be! Remember, we can turn any function into a bound method for an arbitrary class using __get__. That may or may not matter, depending on what you need to do.
What do I mean by that?
defmy_bindable_func(x,a:int,b:str,/,c: dict[str,str]|None,*,d:bool=False,**kwargs,)->str:return''x1: MyCallback = my_bindable_func # This failsx2: MyUnboundCallback = my_bindable_func # This works
x may not be named self, but it’ll get treated as one, because if we do my_bindable_func.__get__(some_obj), then some_obj will be bound to x and callers won’t have to pass anything to x.
Okay, what if you want to return a function that can behave as an unbound method (with self) that can become an unbound method (with __get__)? We can mostly do it with:
And those are type-compatible with the MyCallback and MyUnboundCallback we built earlier, since the signatures match:
# These workcb10: MyUnboundCallback = MyClass.my_methodcb11: MyCallback =MyClass().my_method# These fail correctlycb12: MyUnboundCallback =MyClass().my_methodcb13: MyCallback = MyClass.my_method
And if we wanted, we could modify that ParamSpec going into the MyMethod from make_method() and that’ll impact what the type checkers expect during the call.
Hopefully you can see how this can get complex fast, and involve some tradeoffs.
I personally believe Python needs a lot more love in this area. Types for the different kinds of functions/methods, better specialization for Callable, and some of the useful capabilities from TypeScript would be nice (such as Parameters<T>, ReturnType<T>, OmitThisParameter<T>, etc.). But this is what we have to work with today.
My teachers said to always write a conclusion
What have we learned?
Python’s method signatures are different when bound vs. unbound, and this can affect typing.
Unbound methods aren’t really their own thing, and this can lead to some challenges.
Any method can be a bound method with a call to __get__().
Callable only gets you so far. If you want to type complex functions, write a Protocol with a __call__() signature.
If you want to simulate a bound/unbound-aware type, you’ll need Protocol with __get__().
I feel like I just barely scratched the surface here. There’s a lot more to functions, working with signatures, and challenges around typing than I covered here. We haven’t talked about how you can rewrite signatures on the fly, how annotations are represented, what functions look under the hood, or how bytecode behind functions are mutable at runtime.
I’ll leave some of that for future posts. And I’ll have more to talk about when we expand Typelets with the new parameter inheritance capabilities. It builds upon a lot of what I covered today to perform some very neat and practical tricks for library authors and larger codebases.
What do you think? Did you learn something? Did I get something wrong? Have you done anything interesting or unexpected with signatures or typing around functions you’d like to share? I want to hear about it!
Python dataclasses are a really nice feature for constructing classes that primarily hold or work with data. They can be a good alternative to using dictionaries, since they allow you to add methods, dynamic properties, and subclasses. They can also be a good alternative to building your own class by hand, since they don’t need a custom __init__() that reassigns attributes and provide methods like __eq__() out of the box.
One small tip to keeping dataclasses maintainable is to always construct them with kw_only=True, like so:
from dataclasses import dataclass
@dataclass(kw_only=True)
class MyDataClass:
x: int
y: str
z: bool = True
This will construct an __init__() that looks like this:
class MyDataClass:
def __init__(
self,
*,
x: int,
y: str,
z: bool = True,
) -> None:
self.x = x
self.y = y
self.z = z
Instead of:
class MyDataClass:
def __init__(
self,
x: int,
y: str,
z: bool = True,
) -> None:
self.x = x
self.y = y
self.z = z
That * in the argument list means everything that follows must be passed as a keyword argument, instead of a positional argument.
There are two reasons you probably want to do this:
It allows you to reorder the fields on the dataclass without breaking callers. Positional arguments means a caller can use MyDataClass(1, 'foo', False), and if you remove/reorder any of these arguments, you’ll break those callers unexpectedly. By forcing callers to use MyDataClass(x=1, y='foo', z=False), you remove this risk.
It allows subclasses to add required fields. Normally, any field with a default value (like z above) will force any fields following it to also have a default. And that includes all fields defined by subclasses. Using kw_only=True gives subclasses the flexibility to decide for themselves which fields must be provided by the caller and which have a default.
These reasons are more important for library authors than anything. We spend a lot of time trying to ensure backwards-compatibility and forwards-extensibility in Review Board, so this is an important topic for us. And if you’re developing something reusable with dataclasses, it might be for you, too.
Update: One important point I left out is Python compatibility. This flag was introduced in Python 3.10, so if you’re supporting older versions, you won’t be able to use this just yet. If you want to optimistically enable this just on 3.10+, one approach would be:
import sys
from dataclasses import dataclass
if sys.version_info[:2] >= (3, 10):
dataclass_kwargs = {
'kw_only': True,
}
else:
dataclass_kwargs = {}
...
@dataclass(**dataclass_kwargs)
class MyDataClass:
...
...
But this won’t solve the subclassing issue, so you’d still need to ensure any subclasses use default arguments if you want to support versions prior to 3.10.