crytic_compile.utils.natspec

  1"""
  2Natspec module https://solidity.readthedocs.io/en/latest/natspec-format.html
  3"""
  4from typing import Dict, Optional, Union
  5
  6
  7class UserMethod:
  8    """
  9    Model the user method
 10    """
 11
 12    def __init__(self, method: Union[Dict, str]) -> None:
 13        """Init the object
 14
 15        Args:
 16            method (Union[Dict, str]): Method info (notice)
 17        """
 18        # Constructors dont have "notice: '..'"
 19        if isinstance(method, str):
 20            self._notice: Optional[str] = method
 21        else:
 22            self._notice = method.get("notice", None)
 23
 24    @property
 25    def notice(self) -> Optional[str]:
 26        """Return the method notice
 27
 28        Returns:
 29            Optional[str]: method notice
 30        """
 31        return self._notice
 32
 33    def export(self) -> Dict:
 34        """Export to a python dict
 35
 36        Returns:
 37            Dict: Exported user method
 38        """
 39        return {"notice": self.notice}
 40
 41
 42class DevMethod:
 43    """
 44    Model the dev method
 45    """
 46
 47    def __init__(self, method: Dict) -> None:
 48        """Init the object
 49
 50        Args:
 51            method (Dict): Method infos (author, details, params, return)
 52        """
 53        self._author: Optional[str] = method.get("author", None)
 54        self._details: Optional[str] = method.get("details", None)
 55        self._params: Dict[str, str] = method.get("params", {})
 56        self._return: Optional[str] = method.get("return", None)
 57
 58    @property
 59    def author(self) -> Optional[str]:
 60        """Return the method author
 61
 62        Returns:
 63            Optional[str]: method author
 64        """
 65        return self._author
 66
 67    @property
 68    def details(self) -> Optional[str]:
 69        """Return the method details
 70
 71        Returns:
 72            Optional[str]: method details
 73        """
 74        return self._details
 75
 76    @property
 77    def method_return(self) -> Optional[str]:
 78        """Return the method return
 79
 80        Returns:
 81            Optional[str]: method return
 82        """
 83        return self._return
 84
 85    @property
 86    def params(self) -> Dict[str, str]:
 87        """Return the method params
 88
 89        Returns:
 90            Dict[str, str]: method_name => params
 91        """
 92        return self._params
 93
 94    def export(self) -> Dict:
 95        """Export to a python dict
 96
 97        Returns:
 98            Dict: Exported dev method
 99        """
100        return {
101            "author": self.author,
102            "details": self.details,
103            "params": self.params,
104            "return": self.method_return,
105        }
106
107
108class UserDoc:
109    """
110    Model the user doc
111    """
112
113    def __init__(self, userdoc: dict):
114        """Init the object
115
116        Args:
117            userdoc (dict): User doc (notice, methods)
118        """
119        self._notice: Optional[str] = userdoc.get("notice", None)
120        self._methods: Dict[str, UserMethod] = {
121            k: UserMethod(item) for k, item in userdoc.get("methods", {}).items()
122        }
123
124    @property
125    def notice(self) -> Optional[str]:
126        """Return the user notice
127
128        Returns:
129            Optional[str]: user notice
130        """
131        return self._notice
132
133    @property
134    def methods(self) -> Dict[str, UserMethod]:
135        """Return the user methods
136
137        Returns:
138            Optional[str]: method_name => UserMethod
139        """
140        return self._methods
141
142    def export(self) -> Dict:
143        """Export to a python dict
144
145        Returns:
146            Dict: Exported user doc
147        """
148        return {
149            "methods": {k: items.export() for k, items in self.methods.items()},
150            "notice": self.notice,
151        }
152
153
154class DevDoc:
155    """
156    Model the dev doc
157    """
158
159    def __init__(self, devdoc: Dict):
160        """Init the object
161
162        Args:
163            devdoc (Dict): dev doc (author, details, methods, title)
164        """
165        self._author: Optional[str] = devdoc.get("author", None)
166        self._details: Optional[str] = devdoc.get("details", None)
167        self._methods: Dict[str, DevMethod] = {
168            k: DevMethod(item) for k, item in devdoc.get("methods", {}).items()
169        }
170        self._title: Optional[str] = devdoc.get("title", None)
171
172    @property
173    def author(self) -> Optional[str]:
174        """Return the dev author
175
176        Returns:
177            Optional[str]: dev author
178        """
179        return self._author
180
181    @property
182    def details(self) -> Optional[str]:
183        """Return the dev details
184
185        Returns:
186            Optional[str]: dev details
187        """
188        return self._details
189
190    @property
191    def methods(self) -> Dict[str, DevMethod]:
192        """Return the dev methods
193
194        Returns:
195            Dict[str, DevMethod]: method_name => DevMethod
196        """
197        return self._methods
198
199    @property
200    def title(self) -> Optional[str]:
201        """Return the dev title
202
203        Returns:
204            Optional[str]: dev title
205        """
206        return self._title
207
208    def export(self) -> Dict:
209        """Export to a python dict
210
211        Returns:
212            Dict: Exported dev doc
213        """
214        return {
215            "methods": {k: items.export() for k, items in self.methods.items()},
216            "author": self.author,
217            "details": self.details,
218            "title": self.title,
219        }
220
221
222class Natspec:
223    """
224    Model natspec
225    """
226
227    def __init__(self, userdoc: Dict, devdoc: Dict):
228        """Init the object
229
230        Args:
231            userdoc (Dict): user doc
232            devdoc (Dict): dev doc
233        """
234        self._userdoc: UserDoc = UserDoc(userdoc)
235        self._devdoc: DevDoc = DevDoc(devdoc)
236
237    @property
238    def userdoc(self) -> UserDoc:
239        """Return the userdoc
240
241        Returns:
242            UserDoc: user documentation
243        """
244        return self._userdoc
245
246    @property
247    def devdoc(self) -> DevDoc:
248        """Return the devdoc
249
250        Returns:
251            DevDoc: dev documentation
252        """
253        return self._devdoc