If you have members that users probably shouldn't touch, you prepend them with an underscore. This is just a hint; It doesn't actually change anything. We're all adults here and we know the consequences of reaching into implementation details.

Only then are you truly putting a solid boundary between your library and the folks using your library. Everything else is just praying that you and only you have an underscore on your keyboard! :)

And of course another alternative is to accept that there is no true private in Python other than defdef*, so you allow your ShippingOption to be publicly visible while also documenting that the helper-constructors are what should really be used.

*”defdef” as in function definitions inside other function definitions — closures if you will, although I prefer to write mine as taking most if not all their parameters explicitly:

  def public(foo):
    def private(foo):
      …

    class Private:
      …  # less common

    …

It's sad to see that many features regarding object-oriented programming and static typing are implemented worse in Python than Java. Various examples: __str__() vs. toString(); underscore vs. private; @staticmethod/@classmethod vs. static; generic types are so clunky in Python; types are not shown in the official Python standand library documentation; __init__() doesn't force you to call super() whereas it's mandatory in Java; @override (Python 3.12; year 2023) copying Java @Override (JDK 1.5; year 2004) very late; convention changing from duck typing (always available in Python) to structural typing (optional in Python, mandatory in Java).

In practice, I found it difficult for coworkers to read and understand so I dropped the idea.

Another limitation I found is that it breaks down when you start using inheritance. For example:

```

class _A: pass

A = NewType("A", _A)

class _B(_A): pass

B = NewType("B", _B)

def foo(a: A) -> None: pass

b = B(_B())

foo(b) # Mypy is not happy: Argument 1 to "foo" has incompatible type "B"; expected "A"

foo(A(b)) # Mypy is OK

```

That way, I can use "normal" naming in `class RealShipOpts:...`, and be explicit that it's not really public for the end users (they should use the `.api` module instead).