[Python-Dev] What is a public API?
I thought that the name in a module is in the public interface if: * It doesn't start with an underscore and the module does not have __all__. * It is included in the module's __all__ list. * It is explicitly documented as a part of the public interface. help() uses more complex rules, but it believes __all__ if it defined. But seems there are different views on this. * Raymond suggested to add an underscore the two dozens of names in the calendar module not included in __all__. https://bugs.python.org/issue28292#msg347758 I do not like this idea, because it looks like a code churn and makes the code less readable. * Gregory suggests to document codecs.escape_decode() despite it is not included in __all__. https://bugs.python.org/issue30588 I do not like this idea, because this function always was internal, its only purpose was implementing the "string-escape" codec which was removed in Python 3 (for reasons). In Python 3 it is only used for supporting the old pickle protocol 0. Could we strictly define what is considered a public module interface in Python? ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/SJWR73UOGRSVC3HKHR4SZEJ3KINH32PQ/
[Python-Dev] Re: What is a public API?
On 13.07.2019 23:56, Serhiy Storchaka wrote: I thought that the name in a module is in the public interface if: * It doesn't start with an underscore and the module does not have __all__. * It is included in the module's __all__ list. * It is explicitly documented as a part of the public interface. help() uses more complex rules, but it believes __all__ if it defined. But seems there are different views on this. * Raymond suggested to add an underscore the two dozens of names in the calendar module not included in __all__. https://bugs.python.org/issue28292#msg347758 I do not like this idea, because it looks like a code churn and makes the code less readable. * Gregory suggests to document codecs.escape_decode() despite it is not included in __all__. https://bugs.python.org/issue30588 I do not like this idea, because this function always was internal, its only purpose was implementing the "string-escape" codec which was removed in Python 3 (for reasons). In Python 3 it is only used for supporting the old pickle protocol 0. Could we strictly define what is considered a public module interface in Python? Is "what is present in the reference documentation" insufficient? Documenting all the official guarantees (which the public interface is a part of) is the whole purpose of a reference documentation. (https://softwareengineering.stackexchange.com/questions/373439/technical-documentation-vs-software-design-documentation/373442#373442) ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/SJWR73UOGRSVC3HKHR4SZEJ3KINH32PQ/ -- Regards, Ivan ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/7R6ADYJMEAXI7PPJ5R3VLVVNH4UFSGAY/
[Python-Dev] Re: What is a public API?
> On Jul 13, 2019, at 1:56 PM, Serhiy Storchaka wrote: > > Could we strictly define what is considered a public module interface in > Python? The RealDefinition™ is that whatever we include in the docs is public, otherwise not. Beyond that, there is a question of how users can deduce what is public when they run "import somemodule; print(dir(some module))". In some modules, we've been careful to use both __all__ and to use an underscore prefix to indicate private variables and helper functions (collections and random for example). IMO, when a module has shown that care, future maintainers should stick with that practice. The calendar module is an example of where that care was taken for many years and then a recent patch went against that practice. This came to my attention when an end-user questioned which functions were for internal use only and posted their question on Twitter. On the tracker, I then made a simple request to restore the module's convention but you seem steadfastly resistant to the suggestion. When we do have evidence of user confusion (as in the case with the calendar module), we should just fix it. IMO, it would be an undue burden on the user to have to check every method in dir() against the contents of __all__ to determine what is public (see below). Also, as a maintainer of the module, I would not have found it obvious whether the functions were public or not. The non-public functions look just like the public ones. It's true that the practices across the standard library have historically been loose and varied (__all__ wasn't always used and wasn't always kept up-to-date, some modules took care with private underscore names and some didn't). To me this has mostly worked out fine and didn't require a strict rule for all modules everywhere. IMO, there is no need to sweep through the library and change long-standing policies on existing modules. Raymond -- >>> import calendar >>> dir(calendar) ['Calendar', 'EPOCH', 'FRIDAY', 'February', 'HTMLCalendar', 'IllegalMonthError', 'IllegalWeekdayError', 'January', 'LocaleHTMLCalendar', 'LocaleTextCalendar', 'MONDAY', 'SATURDAY', 'SUNDAY', 'THURSDAY', 'TUESDAY', 'TextCalendar', 'WEDNESDAY', '_EPOCH_ORD', '__all__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', '_colwidth', '_locale', '_localized_day', '_localized_month', '_spacing', 'c', 'calendar', 'datetime', 'day_abbr', 'day_name', 'different_locale', 'error', 'firstweekday', 'format', 'formatstring', 'isleap', 'leapdays', 'main', 'mdays', 'month', 'month_abbr', 'month_name', 'monthcalendar', 'monthlen', 'monthrange', 'nextmonth', 'prcal', 'prevmonth', 'prmonth', 'prweek', 'repeat', 'setfirstweekday', 'sys', 'timegm', 'week', 'weekday', 'weekheader'] ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/ACNDSI6FN6DZKOASNZS4AEQJWWXL6F7Q/
