Commit 17b1d7a2 authored by 20after4's avatar 20after4
Browse files

Document PHIDRef in the README

Change-Id: I6ef1ee5e4f34e31996a86798a681c1430ca07a85
parent 3bf26a6f
......@@ -41,6 +41,44 @@ If you omit the --mock argument then it will request a rather large amount of da
# Example code:
## PHIDRef
Whenever encountering a phabricator `phid`, we use PHIDRef objects to wrap the phid. This provides several conveniences
for working with phabricator objects efficiently. This interactive python session demonstrates how it works:
```python
In [1]: phid = PHIDRef('PHID-PROJ-uier7rukzszoewbhj7ja')
# PHIDRef has a placeholder for the Project instance:
IN [2]: phid.object
Out[2]: Project(name="", phid="PHID-PROJ-uier7rukzszoewbhj7ja")
# Once we call resolve_phids, then the data is filled in from cache or from a conduit request if it's not cached:
In [3]: PHObject.resolve_phids(phab, DataCache(db))
Out[3]: {'PHID-PROJ-uier7rukzszoewbhj7ja': Project(name="Releas...ewbhj7ja")}
# now phid and phid.object are useful:
In [4]: phid.object
Out[4]: Project(name="Release-Engineering-Team", phid="PHID-PROJ-uier7rukzszoewbhj7ja")
In [5]: phid
Out[5]: PHIDRef('PHID-PROJ-uier7rukzszoewbhj7ja', object='Release-Engineering-Team')
In [6]: str(phid.object)
Out[6]: Release-Engineering-Team
In [7]: str(phid)
Out[7]: PHID-PROJ-uier7rukzszoewbhj7ja
```
1. You can construct a bunch of PHIDRef instances and then later on you can fetch all of the data in a single call to `resolve_phids()`.
2. resolve_phids can store a local cache of the phid details in the phobjects table.
3. a PHIDRef can be used transparently as a database key.
* `str(PHIDRef_instance)` returns the original `"PHID-TYPE-hash"` string.
* `PHIDRef_instance.object` returns an instantiated `PHObject` instance.
* After calling `resolve_phids()`, all `PHObject` instances will contain the `name`, `url` and `status` of the corresponding phabricator objects.
```python
from ddd.phab import Conduit
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment