Declare public symbols by Eben60 · Pull Request #811 · JuliaPhysics/Unitful.jl

Eben60 · 2025-09-13T21:52:09Z

Declaration of public symbols as requested in #749

Notes:

I had no idea which symbols maintainers would like to declare as public, thus tried my best guess.
Variable names starting with underscore considered private.
The file public.julia lists non-public symbols, too. That is for maintainers to have an overview, can be removed later, of course.
The file public.julia has non-standard suffix because I remember having some issues with .jl suffix in such a case. It could be CodeCov, not sure. Can be changed to .jl if desired.
See https://github.com/Eben60/Unitful.jl/blob/list_pub_symbols/docs/public_listing.jl to see how the file public.julia was generated.
I've created a testset to check if all variables are declared in one way or another. This testset is put it to the top of runtest.jl because I got errors elswhere (see below).
Declaring VelocityFreeUnits as public (or exported, for that case) leads to failure of the "Display" testset. No idea why, but reproduced on Mac and Ubuntu. For debugging, see https://github.com/Eben60/Unitful.jl/tree/mark_public_units_debug

codecov · 2025-09-13T21:55:37Z

Codecov Report

❌ Patch coverage is 67.56757% with 12 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (master@2eba283). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/user.jl	71.42%	8 Missing ⚠️
src/pkgdefaults.jl	60.00%	2 Missing ⚠️
src/utils.jl	50.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #811   +/-   ##
=========================================
  Coverage          ?   88.90%           
=========================================
  Files             ?       21           
  Lines             ?     1722           
  Branches          ?        0           
=========================================
  Hits              ?     1531           
  Misses            ?      191           
  Partials          ?        0

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

giordano · 2025-09-14T10:42:26Z

src/public.julia

Why .julia extension instead of .jl?

This file is simply unmaintainable. Adding an option to macros like @unit/@dimension/@derived_dimension to make the symbol public looks a much more sustainable solution going forward

Adding an option to macros

I agree, and would look into a macro solution.

Independent on that: Before I continue, I'd prefer to know whether the the variables sorting into private and public, as currently implemented in public.julia is OK, or needs any changes.

May I ask the maintainers to have a look?

I would declare the following as public:

all physical constants,

everything defined through @dimension/@derived_dimension,

AbstractQuantity,

all non-logarithmic units (most of them are defined through @refunit/@unit, but some, like ha and Å, will have to be treated manually). For @affineunit, adding an extra argument to the macro has less of an advantage, since it only defines one symbol, but it could be done just to be consistent with @refunit/@unit.

Those are all the symbols I would declare public right now. Others can be added later.

I’m not sure about the logarithmic units. I wouldn’t declare them public for now, since I consider them broken in a way that cannot be fixed without major (and breaking) changes, but on the other hand, they can be accesssed through u"…" and are widely used (I think).

@sostock On log units: They are intended for the package user, not for some internal purposes. Therefore IMO they should be declared public, too. I'd suggest adding a warning to the docstrings about their experimental nature.

Another question: @dimension returns the dimension, @unit returns the unit, whereas @derived_dimension returns nothing. If that is intended, what's the reason? Otherwise I'd change @derived_dimension to return the dimension, too

@dimension 𝐋 "𝐋" Length true returns Unitful.𝐋 (not Unitful.Length), so if @derived_dimension Area 𝐋^2 true returned something, it should return 𝐋^2, anything else would be inconsistent. But the value 𝐋^2 is not bound to any symbol by the macro, so I can see why there is no use in returning it.

@sostock

everything defined through @dimension/@derived_dimension

Each @dimension defines four bindings, eg. for Lenth we create and declare as public
𝐋, Length, LengthUnits, LengthFreeUnits. My current macro implementation makes all them public - but I'm not sure it is what you meant, or was it just the first two of them.

My current macro implementation makes all them public

That’s what I would do as well.

src/user.jl

sostock

I haven’t reviewed the code yet, these comments are just about the default value of the new argument and the docstrings.

src/user.jl

Co-authored-by: Sebastian Stock <42280794+sostock@users.noreply.github.com>

sostock · 2025-09-29T07:31:48Z

src/pkgdefaults.jl

 \nDimension: [`Unitful.𝐌`](@ref).
 \nSee Also: [`Unitful.kg`](@ref)."
 @unit u      "u" UnifiedAtomicMassUnit 1.660_539_066_60e-27*kg false # (50)
+@public u


Is there a reason why the new macro argument isn’t used here?

changed to use macro argument

Eben60 · 2025-10-03T18:33:45Z

I'd also suggest to declare DefaultSymbols as public and attach docstring to it. @sostock should I?

sostock · 2025-12-30T08:45:53Z

test/runtests.jl

        """
 end

+VERSION >= v"1.11.0-DEV.469" && @testset "Declare Public" begin


The display tests above use if isdefined(Base, :ispublic) instead of VERSION >= v"1.11.0-DEV.469" to test whether public is available. They should all use the same test.

sostock · 2025-12-30T09:24:18Z

test/runtests.jl

 end

+VERSION >= v"1.11.0-DEV.469" && @testset "Declare Public" begin
+    all_public_vars = Symbol[


In my opinion, we don’t need to test all of these. Testing every public symbol means that someone needs to maintain this list (new units get added sometimes). We just need to test that the macros work, so I would test the following:

all symbols for one @dimension

all symbols for one @derived_dimension

one @refunit (the non-prefixed unit and one SI-prefixed unit)

one @unit (the non-prefixed unit and one SI-prefixed unit)

one @affineunit

sostock · 2025-12-30T09:24:41Z

src/user.jl

    esc(expr)
 end

+# TODO update example in the docstring


This TODO should be addressed.

sostock · 2025-12-30T09:26:40Z

test/runtests.jl

+	:μatm, :μb, :μbar, :μcal, :μcd, :μdyn, :μeV, :μerg, :μg, :μkat, :μl, :μlm, :μlx, :μm, :μmol, :μrad, :μs, :μsr,
+	:μyr, :μΩ, :σ, :ϵ0, :𝐈, :𝐉, :𝐋, :𝐌, :𝐍, :𝐓, :𝚯]
+
+    private_vars = Symbol[


In my opinion, we don’t need to test which symbols are private. The fact that they are private means that they can change at any point, so this list would need constant maintenance. I would just remove it.

sostock · 2025-12-30T09:28:13Z

I'd also suggest to declare DefaultSymbols as public and attach docstring to it. @sostock should I?

Yes, I would also declare DefaultSymbols public.

icweaver · 2026-01-29T07:43:42Z

Howdy, have there been any updates on this? Thanks all for your work here!

Eben60 · 2026-01-29T08:24:31Z

I am busy right now on my day job: the deadline is theoretically 2026-03-01. After I am finished there, I hope to be able to continue here.

icweaver · 2026-01-29T08:28:51Z

Appreciate the update, no rush!

Eben60 added 2 commits September 13, 2025 20:44

add declaration of public variables

ec8669e

check if variables declared as public/exported, or listed as private

6cde5e4

giordano requested changes Sep 14, 2025

View reviewed changes

Eben60 added 2 commits September 20, 2025 21:25

Merge branch 'master' into mark_public_units

448bd54

declare public names via macros

2e41dae

Eben60 force-pushed the mark_public_units branch from b7fd95f to 2e41dae Compare September 22, 2025 22:04

sostock reviewed Sep 23, 2025

View reviewed changes

sostock requested changes Sep 23, 2025

View reviewed changes

src/user.jl Outdated Show resolved Hide resolved

Eben60 added 2 commits September 26, 2025 23:50

change makepublic=autodocs to makepublic=false

47657b4

change docstrings due to changed display after declaring vars as public

e7cd240

sostock reviewed Sep 27, 2025

View reviewed changes

src/user.jl Outdated Show resolved Hide resolved

Eben60 and others added 2 commits September 27, 2025 16:30

remove empty line

5296073

Co-authored-by: Sebastian Stock <42280794+sostock@users.noreply.github.com>

set makepublic=false; add testset "Declare Public"

9011846

Eben60 marked this pull request as ready for review September 27, 2025 20:23

sostock reviewed Sep 29, 2025

View reviewed changes

replace explicit declaration of :u as public by @Unit macro argument

1321861

sostock reviewed Dec 30, 2025

View reviewed changes

src/user.jl

esc(expr)

end

# TODO update example in the docstring

Copy link

Collaborator

sostock Dec 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This TODO should be addressed.

sostock reviewed Dec 30, 2025

View reviewed changes

Conversation

Eben60 commented Sep 13, 2025

Uh oh!

codecov bot commented Sep 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sostock left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Eben60 commented Oct 3, 2025

Uh oh!

sostock Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sostock commented Dec 30, 2025

Uh oh!

icweaver commented Jan 29, 2026

Uh oh!

Eben60 commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

icweaver commented Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Sep 13, 2025 •

edited

Loading

sostock Dec 30, 2025 •

edited

Loading

Eben60 commented Jan 29, 2026 •

edited

Loading