Fix several small things found during PR #566 review

[jholveck]

While reviewing PR #566, I had some small cleanups. Some of these were in the PR code, but many were things I found in nearby code during the review.

Rather than hold up the commit, I put these in this new PR.

• Prefer Sphinx-friendly docstrings for attributes on Monitor
• Use primary_monitor instead of monitors[1] in multiple places.
• Remove :returns: when it's obvious.
• Clarify "string-key access" in the docs.
• Rename _RandROutputIds -> _RandROutputInfo, since it's not the ID. In fact, it doesn't even include the XID that XRandR uses. (The unique_id is something different, a URL encoding of certain EDID data.)
• Fix typo
• Remove dict-oriented phrasing in some docstrings for methods that accept or return a Monitor or Region.
• Remove "See :meth:monitors <monitors> for monitor object details." from grab, since the types it accepts now define the required format.
• Validate regions passed to grab, and coerce coordinates to ints.
• Make the docstring for "MSS.monitors" more user-oriented, instead of developer-oriented.
• Handle the case of an incorrect type passed to grab. Note: Should this be a TypeError or a ScreenShotError?
• In MSS.save:
  • Use the local time zone instead of UTC.
  • Use the same date for all filenames.
  • Capture all the screenshots before returning.
  • Return a Sequence instead of a generator Iterator. A Sequence seems to be a more reasonable type. This also removes the need to consume the return value to complete the operation. This is an incompatible change, since next can't be called on a sequence. However, both the old and new versions work with for loops or with next(iter(sct.save(...))).
• Where example monitor attributes (not all of them) were listed in a bulleted list, change those to prose text and make it clear that they aren't an exhaustive list.

I have two notes from #566 that I didn't address in this PR.

Regarding tests/test_models.py:

I question the utility of several of the tests in this file, but I'm not going to say that they need to be deleted.

Regarding changes to docs/source/usage.rst:

This "Capturing Screenshots" section is meant to be a "how to get started" introduction to MSS. It tries to focus on the essentials, and avoid confusing new users.

With that in mind, most of this seems to be just an unnecessary distraction. It increases the cognitive load on new users. For instance, are new users who are just learning the basics likely to care that **monitor unpacking is not supported? It's just extra stuff that they don't have to care about, but still have to spend cognitive cycles to decide if they care.

For the purposes of this flow, I think that explaining all about a Monitor object may be a bit too much. I might suggest putting the details in a separate section or subsection, or even just using some cross-references into the API reference for some details. Putting some of this into a separate section can help with cognitive chunking, and let the user get a basic flow before trying to absorb a lot of the details.

Changes proposed in this PR

• Tests added/updated
• Documentation updated
• Changelog entry added
• ./check.sh passed

AI assistance disclosure

• No AI assistance was used to generate this contribution. - AI assistance used

[halldorfannar]

Should we perhaps keep the copy and instead add a __post__init__ to Region class?

[jholveck]

I'm okay with that; would you prefer it that way, or is this just you mentioning an alternative?

[halldorfannar]

Yes, I prefer it slightly but not a hill that I'm ready to die on! 😄

[jholveck]

Ok, done! I'm using deepcopy.replace instead of copy.copy, since the latter doesn't call __post_init__.

[halldorfannar]

The __post_init__ would handle this as well.

[halldorfannar]

Looks good! Just had those questions about the __post_init__.

[jholveck]

I spoke with @halldorfannar , and he's fine with the Region.__post_init__ commit as well.