MNT/DOC: parse valid json db, improve docstring

[tangkong]

Description

• Slightly modifies the happi update command to handle json formatted similar to a valid json database.
• Updates the happi update docstring (and by proxy help text) to better describe the use case

Now happi update can take JSON input that looks like a working json backend:

Details

  {
      "al1k2": {
          "_id": "al1k2",
          "active": true,
          "args": [
              "{{prefix}}"
          ],
          <...>
          "type": "pcdsdevices.happi.containers.LCLSItem",
          "z": 778.833
      }
  }

or a list of items in json form (original functionality):

Details

[{
      "_id": "al1k2",
      "active": true,
      "args": [
          "{{prefix}}"
      ],
      <...>
      "type": "pcdsdevices.happi.containers.LCLSItem",
      "z": 778.833
}]

Usage is now described in the subcommand. One can either pipe input and tell happi to look at stdin:

cat my.json | happi update -

or use command substitution

happi update $(cat my.json)

Motivation and Context

#319

Click does not inherently read from stdin, we must explicitly tell it to. If we do this, piping output will work

How Has This Been Tested?

interactively

Where Has This Been Documented?

This PR

Pre-merge checklist

• Code works interactively
• Code contains descriptive docstrings, including context and API
• New/changed functions and methods are covered in the test suite where possible
• Test suite passes locally
• Test suite passes on GitHub Actions
• Ran docs/pre-release-notes.sh and created a pre-release documentation page
• Pre-release docs include context, functional descriptions, and contributors as appropriate

[ZLLentz]

I think this looks correct to me. Is there any obvious way we can unit test this behavior?

[tangkong]

I'll give unit tests a quick shot, surely there's some stdin mocking in click

[untzag]

this works great for me, thanks so much @tangkong

[untzag]

@tangkong consider using subprocess for unit tests? You could set environment variables and use a tempfile for the database itself.

[ZLLentz]

I think the test looks good, it would have caught this regression