Incorrect docstring in Job.update_statepoint

[bdice]

The docstring modified by @cbkerr in #444 has a small error / confusing wording. Here, the Job.update_statepoint method claims that setting overwrite=True makes the method update_statepoint act like the method reset_statepoint. This is not quite true, and nearly caused me to re-implement the behavior incorrectly while refactoring #497.

signac/signac/contrib/job.py

Lines 407 to 408 in 9bb8887

	to a job's statepoint, making it equivalent to
	:meth:`~.reset_statepoint`. Use with caution!

For example, see this minimal reproduction:

import signac
project = signac.init_project("UpdateStatepointDocstringBug")
job = project.open_job({"a": 1})
print(job.sp)
job.update_statepoint({"b": 2}, overwrite=True)   # Here the overwrite behavior doesn't matter because the key does not exist yet
print(job.sp)
job.update_statepoint({"b": 3})
print(job.sp)

Output:

{'a': 1}
{'a': 1, 'b': 2}
Traceback (most recent call last):
  File "problem.py", line 7, in <module>
    job.update_statepoint({"b": 3})
  File "/home/bdice/code/signac/signac/contrib/job.py", line 414, in update_statepoint
    raise KeyError(key)
KeyError: 'b'

Notice that when overwrite=True, the Job.update_statepoint method acts like dict.update in its behavior of overwriting values: https://docs.python.org/3/library/stdtypes.html#dict.update

I suggest rewriting the docstring:

        Parameters
        ----------
        update : dict
            A mapping used for the state point update.
        overwrite : bool, optional
            If False, an error will be raised if the update modifies the
            values of existing keys in the state point. If True, any existing
            keys will be overwritten in the same way as :meth:`dict.update`.
            Use with caution! (Default value = False).

This also affects Project.update_statepoint.

[cbkerr]

I think we missed what the old docstring meant by: "Set [overwrite] to true to ignore whether this update overwrites parameters [that] are currently part of the job's state point." It didn't address the false case. But now we know!

I'll fix with your change

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[bdice]

This isn't complete but I'm opening a PR to resolve it and will tag @cbkerr for review.