chore: Bump version manually only in pyproject.toml

[FBruzzesi]

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• Related comment

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes

[FBruzzesi]

I can definitly replicate the issue locally, but I hoped that it was some env issue 🥲
It looks like that pre-commit does not install narwhals when running check-api-reference 🤔

Edit: changing the following:

- entry: python -m utils.check_api_reference
+ entry: python utils/check_api_reference.py

leads to

ModuleNotFoundError: No module named 'narwhals'

so yes, narwhals is not installed 🤔

[dangotbanned]

@FBruzzesi I wonder if the new uv version command might be helpful for us here?

• https://docs.astral.sh/uv/reference/cli/#uv-version
• https://github.com/astral-sh/uv/releases/tag/0.7.0

[FBruzzesi]

@FBruzzesi I wonder if the new uv version command might be helpful for us here?

• https://docs.astral.sh/uv/reference/cli/#uv-version
• https://github.com/astral-sh/uv/releases/tag/0.7.0

@dangotbanned this PR was aiming at something else, but we could definitly replace:

narwhals/utils/bump_version.py

Lines 45 to 57 in 42813b4

	with open("pyproject.toml", encoding="utf-8") as f:
	content = f.read()
	old_version = re.search(r'version = "(.*)"', content).group(1) # pyright: ignore[reportOptionalMemberAccess]
	version = old_version.split(".")
	if how == "patch":
	version = ".".join(version[:-1] + [str(int(version[-1]) + 1)])
	elif how == "minor":
	version = ".".join(version[:-2] + [str(int(version[-2]) + 1), "0"])
	elif how == "major":
	version = ".".join([str(int(version[0]) + 1), "0", "0"])
	content = content.replace(f'version = "{old_version}"', f'version = "{version}"')
	with open("pyproject.toml", "w", encoding="utf-8") as f:
	f.write(content)

with

subprocess.run(["uv", "version", "--bump", how])

🤩

[dangotbanned]

Thanks @FBruzzesi 🥳

[MarcoGorelli]

To be completely honest I'd rather just update in two places, I have no idea what this is doing

Happy to take the installation update in the docs page though 👍

[FBruzzesi]

Just to make sure I understand correctly - the concern with importing importlib.metadata is regarding startup time? see comment

[MarcoGorelli]

i feel uneasy about the global - do you have a reference from another project that does this?

[FBruzzesi]

Looking for __version__ = version(__name__) on github you will get many results

A couple of projects I know that made it in the first few pages of the list are:

• connector-x
• manim
• patito (in a try-except block)

Edit: some other project do the analogous of __version__ = version("narwhals") (but couldn't find something I know)

[MarcoGorelli]

sure, thanks

still not sure we need it though - there's some other nice improvements in here though, happy to take those

regarding perf, from narwhals import __version__ currently takes 0m0.156s, and from importlib import metadata takes 0m0.108s

[dangotbanned]

Some notes:

• __version__ doesn't seem to be mentioned as a standard in the python docs
  • I understand lots of packages seem to provide it anyway, but I'm not sure where the pattern is documented
• __getattr__ is a well-defined method of deferring imports
  • https://docs.python.org/3/reference/datamodel.html#customizing-module-attribute-access
• There are going to be many more examples of this pattern following 3.14
  • https://docs.python.org/3.14/whatsnew/3.14.html#optimizations
  • Improve import time of various stdlib modules python/cpython#118761
    • gh-118761: Lazily import annotationlib in typing python/cpython#132060
    • gh-118761: Reduce import time of gettext.py by delaying re import python/cpython#128898
    • gh-118761: Always lazy import re in locale python/cpython#129860

IMO, I don't think there's a use-case for checking narwhals.__version__, but if people want to do that - the cost of it isn't paid by everyone else since we're providing it lazily.
Are there any search results of a package checking it? (sorry I'm replying from my phone 😅)

@MarcoGorelli I understand your caution and ultimately will defer 😉 to you, but I think this balances:

• Theoretical backwards-compatibility
• Avoids introducing performance overhead for those that don't need it
• Ensures that potential cost is only paid once
• Lowers our maintenance burden, by simplifying version bumps

[MarcoGorelli]

thanks - could you elaborate on the global part please? i've had a look at the linked projects and they don't seem to have it

if we don't deem __version__ to be useful to most users, presumably we don't need the global either?

[dangotbanned]

thanks - could you elaborate on the global part please? i've had a look at the linked projects and they don't seem to have it

Sure @MarcoGorelli!

I'm assuming you're referring to the projects in (#2514 (comment))?
The 3 stdlib examples I gave in (#2514 (comment)) all featured use of global:

• https://github.com/python/cpython/pull/132060/files
• https://github.com/python/cpython/pull/128898/files
• https://github.com/python/cpython/pull/129860/files

I guess for some more info on global, these might be helpful

• https://docs.python.org/3/tutorial/classes.html#python-scopes-and-namespaces
• https://docs.python.org/3/tutorial/classes.html#scopes-and-namespaces-example
• https://docs.python.org/3/reference/simple_stmts.html#global
• https://docs.python.org/3/reference/datamodel.html#modules
• https://docs.python.org/3/reference/datamodel.html#module.__dict__

As a more concrete example, we can do the following on main:

import narwhals as nw

>>> nw.__version__
'1.38.2'
>>> "__version__" in nw.__dict__
True
>>> nw.__dict__["__version__"]
'1.38.2'
>>> nw.__version__ == nw.__dict__["__version__"] == nw.__dict__.__getitem__("__version__")
True

But in this PR, we can see where the __getattr__ hook slips in:

import narwhals as nw

>>> nw.__dict__["__version__"]
KeyError: '__version__'
>>> nw.__version__
'1.38.2'
>>> nw.__dict__["__version__"]
'1.38.2'

Without the global:

• __version__ is never added to nw.__dict__
• Each lookup of nw.__version__ always goes via __getattr__, which is triggered after the regular __dict__ lookup fails

So the global is what provides the lazy import, since the work is only ever done once and only when a user asks for it 🙂.
All subsequent lookups behave identically to a regular lookup into the namespace.

---

As another example, polars has 2 behaviors related to __getattr__:

• Deprecations are triggered on every lookup
  • E.g. pl.NUMERIC_DTYPES
• Dependencies use much more magic than I understand 😄, but they eventually resolve to replacing a module's globals
  • https://github.com/pola-rs/polars/blob/34b5729cec09a8e3619c70844a77830c0613f070/py-polars/polars/dependencies.py#L71-L76

[dangotbanned]

Interestingly, polars seems to be fine with using find_spec and still considers that lazy

• https://github.com/pola-rs/polars/blob/34b5729cec09a8e3619c70844a77830c0613f070/py-polars/polars/dependencies.py#L134
• https://github.com/pola-rs/polars/blob/34b5729cec09a8e3619c70844a77830c0613f070/py-polars/polars/dependencies.py#L173-L194

[MarcoGorelli]

thanks for the detailed explanations and for bearing with me on this one, really appreciate it

thanks both!