Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix documentation of epoch/time.time #88035

Closed
ofek mannequin opened this issue Apr 16, 2021 · 8 comments
Closed

Fix documentation of epoch/time.time #88035

ofek mannequin opened this issue Apr 16, 2021 · 8 comments
Labels
3.11 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@ofek
Copy link
Mannequin

ofek mannequin commented Apr 16, 2021

BPO 43869
Nosy @vstinner, @ofek, @pganssle, @miguendes
PRs
  • bpo-43869: Improve epoch docs #25777
  • bpo-43869: Time Epoch is the same on all platforms #30664
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = <Date 2022-01-19.10:27:50.486>
    created_at = <Date 2021-04-16.15:15:58.550>
    labels = ['3.11', 'type-feature', 'docs']
    title = 'Fix documentation of epoch/time.time'
    updated_at = <Date 2022-01-19.10:27:50.485>
    user = 'https://github.com/ofek'

    bugs.python.org fields:

    activity = <Date 2022-01-19.10:27:50.485>
    actor = 'vstinner'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2022-01-19.10:27:50.486>
    closer = 'vstinner'
    components = ['Documentation']
    creation = <Date 2021-04-16.15:15:58.550>
    creator = 'Ofekmeister'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 43869
    keywords = ['patch']
    message_count = 8.0
    messages = ['391214', '391215', '391216', '391218', '392583', '410875', '410876', '410934']
    nosy_count = 5.0
    nosy_names = ['vstinner', 'docs@python', 'Ofekmeister', 'p-ganssle', 'miguendes']
    pr_nums = ['25777', '30664']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue43869'
    versions = ['Python 3.11']

    Linked PRs

    @ofek
    Copy link
    Mannequin Author

    ofek mannequin commented Apr 16, 2021

    The descriptions for the following:

    indicate that it is platform dependent. However, that is likely untrue. See the brief discussion here: DataDog/integrations-core#6692 (comment)

    @ofek ofek mannequin added 3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes 3.10 only security fixes labels Apr 16, 2021
    @ofek ofek mannequin assigned docspython Apr 16, 2021
    @ofek ofek mannequin added docs Documentation in the Doc dir 3.7 (EOL) end of life type-feature A feature request or enhancement 3.8 only security fixes 3.9 only security fixes 3.10 only security fixes labels Apr 16, 2021
    @ofek ofek mannequin assigned docspython Apr 16, 2021
    @ofek ofek mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Apr 16, 2021
    @vstinner
    Copy link
    Member

    On Windows 10 (build 20H2), I get:

    Python 3.10.0a7+ (heads/master:b136b1aac4, Apr 16 2021, 14:36:39) [MSC v.1928 64 bit (AMD64)] on win32
    >>> import time
    >>> time.gmtime(0)
    time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0)

    @vstinner
    Copy link
    Member

    time.time doc says "On Windows and most Unix systems, the epoch is January 1, 1970, 00:00:00 (UTC)"

    The epoch doc says "For Unix, the epoch is January 1, 1970, 00:00:00 (UTC)".

    At least, the epoch doc can be completed to also mention that it's the same on Windows.

    @vstinner
    Copy link
    Member

    "platform dependent" was added in 2017 by the commit (bpo-29026):

    commit 23557d5
    Author: Eric Appelt <eric.appelt@gmail.com>
    Date: Thu Feb 16 05:00:45 2017 -0500

    bpo-29026: Clarify documentation of time.time (#34)
    
    * bpo-29026: Clarity documentation of time.time
    
    Clarify the documentation of time.time by more
    precisely defining what is meant by "seconds since
    the epoch" on most platforms. Additionally explain
    how gmtime and localtime may be used to extract
    calendar components and convert to a more common
    date format.
    
    * bpo-29026: Minor improvements for time.time doc
    
    * bpo-29026: Consistency fixes for time.time doc
    

    ---

    MS-DOS (no longer supported by Python since 2014) uses 1980-01-01 epoch.

    The Windows FILETIME type uses 1601-01-01 epoch. Python has convention functions to the Unix 1970-01-01 Epoch:

    static __int64 secs_between_epochs = 11644473600; /* Seconds between 1.1.1601 and 1.1.1970 */

    static void
    FILE_TIME_to_time_t_nsec(FILETIME *in_ptr, time_t *time_out, int* nsec_out)
    {
        /* XXX endianness. Shouldn't matter, as all Windows implementations are little-endian */
        /* Cannot simply cast and dereference in_ptr,
           since it might not be aligned properly */
        __int64 in;
        memcpy(&in, in_ptr, sizeof(in));
        *nsec_out = (int)(in % 10000000) * 100; /* FILETIME is in units of 100 nsec. */
        *time_out = Py_SAFE_DOWNCAST((in / 10000000) - secs_between_epochs, __int64, time_t);
    }
    
    void
    _Py_time_t_to_FILE_TIME(time_t time_in, int nsec_in, FILETIME *out_ptr)
    {
        /* XXX endianness */
        __int64 out;
        out = time_in + secs_between_epochs;
        out = out * 10000000 + nsec_in / 100;
        memcpy(out_ptr, &out, sizeof(out));
    }

    More epochs for more fun:
    https://en.wikipedia.org/wiki/Epoch_(computing)#Notable_epoch_dates_in_computing

    @miguendes
    Copy link
    Mannequin

    miguendes mannequin commented May 1, 2021

    Seen that no one is working on this issue I created an PR to clarify the docs.

    #25777

    @vstinner
    Copy link
    Member

    New changeset ff7703c by Miguel Brito in branch 'main':
    bpo-43869: Improve epoch docs (GH-25777)
    ff7703c

    @vstinner
    Copy link
    Member

    I was going to close the change, but I had a last look and... oh... I found that the Python test suite checks that the Epoch is 1970-01-01 at 00:00 since 2008! I wrote #74849 to add an explicit test and I updated the doc.

    @iritkatriel iritkatriel added 3.11 only security fixes and removed 3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes 3.10 only security fixes labels Jan 18, 2022
    @iritkatriel iritkatriel removed the 3.10 only security fixes label Jan 18, 2022
    @vstinner
    Copy link
    Member

    New changeset a847785 by Victor Stinner in branch 'main':
    bpo-43869: Time Epoch is the same on all platforms (GH-30664)
    a847785

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    litlighilit added a commit to litlighilit/cpython that referenced this issue Apr 19, 2024
    The epoch is `January 1st, 1970 on all platforms`, according to python#88035
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.11 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    2 participants