The short description of epoll.poll is correct (gives timeout unit as seconds [float]; includes maxevents).  However, the long description lists the timeout units as milliseconds ("If timeout is given, it specifies the length of time in milliseconds which the system will wait for events before returning."), and does not include maxevents at all.

See https://docs.python.org/3.5/library/select.html#select.poll.poll

See also https://docs.python.org/2.7/library/select.html#select.poll.poll

Thanks for the report. In the title, you mentioned epoll.poll(), but you gave the link to the poll.poll() documentation. Also, the part you quoted

    If timeout is given, it specifies the length of time in milliseconds
    which the system will wait for events before returning.

is from the poll.poll() documentation.

Currently, the documentation for epoll.poll() is pretty minimal:

    epoll.poll(timeout=-1, maxevents=-1)
    
    Wait for events. timeout in seconds (float)

There is an open issue to improve epoll.poll() documentation: Issue 29247. Also, there is a review comment about explaining the *maxevent* parameter (https://github.com/python/cpython/pull/4798/files#r174309761), so I'm going to address the issues you've mentioned in msg266118 as part of issue 29247.

In the meantime, I'm closing this as a duplicate of issue 29247.