|
1 | 1 | from __future__ import division |
2 | 2 | import sys |
| 3 | +from cbook import iterable, flatten |
3 | 4 | from transforms import identity_transform |
4 | 5 |
|
5 | 6 | ## Note, matplotlib artists use the doc strings for set and get |
@@ -174,3 +175,250 @@ def update_from(self, other): |
174 | 175 | self._lod = other._lod |
175 | 176 | self._label = other._label |
176 | 177 |
|
| 178 | + |
| 179 | +class ArtistInspector: |
| 180 | + """ |
| 181 | + A helper class to insect an Artist and return information about |
| 182 | + it's settable properties and their current values |
| 183 | + """ |
| 184 | + def __init__(self, o): |
| 185 | + """ |
| 186 | + Initialize the artist inspector with an artist or sequence of |
| 187 | + artists. Id a sequence is used, we assume it is a homogeneous |
| 188 | + sequence (all Artists are of the same type) and it is your |
| 189 | + responsibility to make sure this is so. |
| 190 | + """ |
| 191 | + if iterable(o): o = o[0] |
| 192 | + self.o = o |
| 193 | + self.aliasd = self.get_aliases() |
| 194 | + |
| 195 | + def get_aliases(self): |
| 196 | + """ |
| 197 | + get a dict mapping fullname -> alias for each alias in o. |
| 198 | + Eg for lines: {'markerfacecolor': 'mfc', |
| 199 | + 'linewidth' : 'lw', |
| 200 | + } |
| 201 | + """ |
| 202 | + names = [name for name in dir(self.o) if |
| 203 | + (name.startswith('set_') or name.startswith('get_')) |
| 204 | + and callable(getattr(self.o,name))] |
| 205 | + aliases = {} |
| 206 | + for name in names: |
| 207 | + func = getattr(self.o, name) |
| 208 | + if not self.is_alias(func): continue |
| 209 | + docstring = func.__doc__ |
| 210 | + fullname = docstring[10:] |
| 211 | + aliases[fullname[4:]] = name[4:] |
| 212 | + return aliases |
| 213 | + |
| 214 | + def get_valid_values(self, attr): |
| 215 | + """ |
| 216 | + get the legal arguments for the setter associated with attr |
| 217 | +
|
| 218 | + This is done by querying the doc string of the function set_attr |
| 219 | + for a line that begins with ACCEPTS: |
| 220 | +
|
| 221 | + Eg, for a line linestyle, return |
| 222 | + [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ] |
| 223 | + """ |
| 224 | + |
| 225 | + name = 'set_%s'%attr |
| 226 | + if not hasattr(self.o, name): |
| 227 | + raise AttributeError('%s has no function %s'%(self.o,name)) |
| 228 | + func = getattr(self.o, name) |
| 229 | + |
| 230 | + docstring = func.__doc__ |
| 231 | + if docstring is None: return 'unknown' |
| 232 | + |
| 233 | + if docstring.startswith('alias for '): |
| 234 | + return None |
| 235 | + for line in docstring.split('\n'): |
| 236 | + line = line.lstrip() |
| 237 | + if not line.startswith('ACCEPTS:'): continue |
| 238 | + return line[8:].strip() |
| 239 | + return 'unknown' |
| 240 | + |
| 241 | + def get_setters(self): |
| 242 | + """ |
| 243 | + Get the attribute strings with setters for object h. Eg, for a line, |
| 244 | + return ['markerfacecolor', 'linewidth', ....] |
| 245 | + """ |
| 246 | + |
| 247 | + setters = [] |
| 248 | + for name in dir(self.o): |
| 249 | + if not name.startswith('set_'): continue |
| 250 | + o = getattr(self.o,name) |
| 251 | + if not callable(o): continue |
| 252 | + func = o |
| 253 | + if self.is_alias(func): continue |
| 254 | + setters.append(name[4:]) |
| 255 | + return setters |
| 256 | + |
| 257 | + def is_alias(self, o): |
| 258 | + 'return true if method object o is an alias for another function' |
| 259 | + ds = o.__doc__ |
| 260 | + if ds is None: return False |
| 261 | + return ds.startswith('alias for ') |
| 262 | + |
| 263 | + def aliased_name(self, s): |
| 264 | + """ |
| 265 | + return 'PROPNAME or alias' if s has an alias, else return |
| 266 | + PROPNAME. |
| 267 | +
|
| 268 | + Eg for the line markerfacecolor property, which has an alias, |
| 269 | + return 'markerfacecolor or mfc' and for the transform |
| 270 | + property, which does not, return 'transform' |
| 271 | + """ |
| 272 | + if self.aliasd.has_key(s): |
| 273 | + return '%s or %s' % (s, self.aliasd[s]) |
| 274 | + else: return s |
| 275 | + |
| 276 | + def pprint_setters(self, prop=None): |
| 277 | + """ |
| 278 | + if prop is None, return a list of strings of all settable properies |
| 279 | + and their valid values |
| 280 | +
|
| 281 | + if prop is not None, it is a valid property name and that |
| 282 | + property will be returned as a string of property : valid |
| 283 | + values |
| 284 | + """ |
| 285 | + if prop is not None: |
| 286 | + accepts = self.get_valid_values(prop) |
| 287 | + return ' %s: %s' %(prop, accepts) |
| 288 | + |
| 289 | + attrs = self.get_setters() |
| 290 | + attrs.sort() |
| 291 | + lines = [] |
| 292 | + |
| 293 | + for prop in attrs: |
| 294 | + accepts = self.get_valid_values(prop) |
| 295 | + name = self.aliased_name(prop) |
| 296 | + lines.append(' %s: %s' %(name, accepts)) |
| 297 | + return lines |
| 298 | + |
| 299 | + def pprint_getters(self): |
| 300 | + """ |
| 301 | + return the getters and actual values as list of strings' |
| 302 | + """ |
| 303 | + getters = [name for name in dir(self.o) |
| 304 | + if name.startswith('get_') |
| 305 | + and callable(getattr(self.o, name))] |
| 306 | + getters.sort() |
| 307 | + lines = [] |
| 308 | + for name in getters: |
| 309 | + func = getattr(self.o, name) |
| 310 | + if self.is_alias(func): continue |
| 311 | + try: val = func() |
| 312 | + except: continue |
| 313 | + if hasattr(val, 'shape') and len(val)>6: |
| 314 | + s = str(val[:6]) + '...' |
| 315 | + else: |
| 316 | + s = str(val) |
| 317 | + name = self.aliased_name(name[4:]) |
| 318 | + lines.append(' %s = %s' %(name, s)) |
| 319 | + return lines |
| 320 | + |
| 321 | + |
| 322 | +def get(o, *args): |
| 323 | + """ |
| 324 | + Return the value of handle property s |
| 325 | +
|
| 326 | + h is an instance of a class, eg a Line2D or an Axes or Text. |
| 327 | + if s is 'somename', this function returns |
| 328 | +
|
| 329 | + o.get_somename() |
| 330 | +
|
| 331 | + get can be used to query all the gettable properties with get(o) |
| 332 | + Many properties have aliases for shorter typing, eg 'lw' is an |
| 333 | + alias for 'linewidth'. In the output, aliases and full property |
| 334 | + names will be listed as |
| 335 | +
|
| 336 | + property or alias = value |
| 337 | +
|
| 338 | + eg |
| 339 | +
|
| 340 | + linewidth or lw = 2 |
| 341 | + """ |
| 342 | + |
| 343 | + insp = ArtistInspector(o) |
| 344 | + |
| 345 | + if len(args)==0: |
| 346 | + print '\n'.join(insp.pprint_getters()) |
| 347 | + return |
| 348 | + |
| 349 | + name = args[0] |
| 350 | + func = getattr(o, 'get_' + name) |
| 351 | + return func() |
| 352 | + |
| 353 | +def set(h, *args, **kwargs): |
| 354 | + """ |
| 355 | + matlab(TM) and pylab allow you to use set and get to set and get |
| 356 | + object properties, as well as to do introspection on the object |
| 357 | + For example, to set the linestyle of a line to be dashed, you can do |
| 358 | +
|
| 359 | + >>> line, = plot([1,2,3]) |
| 360 | + >>> set(line, linestyle='--') |
| 361 | +
|
| 362 | + If you want to know the valid types of arguments, you can provide the |
| 363 | + name of the property you want to set without a value |
| 364 | +
|
| 365 | + >>> set(line, 'linestyle') |
| 366 | + linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ] |
| 367 | +
|
| 368 | + If you want to see all the properties that can be set, and their |
| 369 | + possible values, you can do |
| 370 | +
|
| 371 | +
|
| 372 | + >>> set(line) |
| 373 | + ... long output listing omitted' |
| 374 | +
|
| 375 | + set operates on a single instance or a list of instances. If you are |
| 376 | + in quey mode introspecting the possible values, only the first |
| 377 | + instance in the sequnce is used. When actually setting values, all |
| 378 | + the instances will be set. Eg, suppose you have a list of two lines, |
| 379 | + the following will make both lines thicker and red |
| 380 | +
|
| 381 | + >>> x = arange(0,1.0,0.01) |
| 382 | + >>> y1 = sin(2*pi*x) |
| 383 | + >>> y2 = sin(4*pi*x) |
| 384 | + >>> lines = plot(x, y1, x, y2) |
| 385 | + >>> set(lines, linewidth=2, color='r') |
| 386 | +
|
| 387 | + Set works with the matlab(TM) style string/value pairs or with python |
| 388 | + kwargs. For example, the following are equivalent |
| 389 | +
|
| 390 | + >>> set(lines, 'linewidth', 2, 'color', r') # matlab style |
| 391 | + >>> set(lines, linewidth=2, color='r') # python style |
| 392 | + """ |
| 393 | + |
| 394 | + insp = ArtistInspector(h) |
| 395 | + |
| 396 | + if len(kwargs)==0 and len(args)==0: |
| 397 | + print '\n'.join(insp.pprint_setters()) |
| 398 | + return |
| 399 | + |
| 400 | + if len(kwargs)==0 and len(args)==1: |
| 401 | + print insp.pprint_setters(prop=args[0]) |
| 402 | + return |
| 403 | + |
| 404 | + if not iterable(h): h = [h] |
| 405 | + else: h = flatten(h) |
| 406 | + |
| 407 | + |
| 408 | + if len(args)%2: |
| 409 | + raise ValueError('The set args must be string, value pairs') |
| 410 | + |
| 411 | + funcvals = [] |
| 412 | + for i in range(0, len(args)-1, 2): |
| 413 | + funcvals.append((args[i], args[i+1])) |
| 414 | + funcvals.extend(kwargs.items()) |
| 415 | + |
| 416 | + ret = [] |
| 417 | + for o in h: |
| 418 | + for s, val in funcvals: |
| 419 | + s = s.lower() |
| 420 | + funcName = "set_%s"%s |
| 421 | + func = getattr(o,funcName) |
| 422 | + ret.extend( [func(val)] ) |
| 423 | + return [x for x in flatten(ret)] |
| 424 | + |
0 commit comments