1 #!/usr/bin/env python 2 3 # Copyright (C) 2014 The Android Open Source Project 4 # 5 # Licensed under the Apache License, Version 2.0 (the 'License'); 6 # you may not use this file except in compliance with the License. 7 # You may obtain a copy of the License at 8 # 9 # http://www.apache.org/licenses/LICENSE-2.0 10 # 11 # Unless required by applicable law or agreed to in writing, software 12 # distributed under the License is distributed on an 'AS IS' BASIS, 13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 # See the License for the specific language governing permissions and 15 # limitations under the License. 16 17 """ 18 Enforces common Android public API design patterns. It ignores lint messages from 19 a previous API level, if provided. 20 21 Usage: apilint.py current.txt 22 Usage: apilint.py current.txt previous.txt 23 24 You can also splice in blame details like this: 25 $ git blame api/current.txt -t -e > /tmp/currentblame.txt 26 $ apilint.py /tmp/currentblame.txt previous.txt --no-color 27 """ 28 29 import re, sys, collections, traceback, argparse 30 31 32 BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE = range(8) 33 34 ALLOW_GOOGLE = False 35 USE_COLOR = True 36 37 def format(fg=None, bg=None, bright=False, bold=False, dim=False, reset=False): 38 # manually derived from http://en.wikipedia.org/wiki/ANSI_escape_code#Codes 39 if not USE_COLOR: return "" 40 codes = [] 41 if reset: codes.append("0") 42 else: 43 if not fg is None: codes.append("3%d" % (fg)) 44 if not bg is None: 45 if not bright: codes.append("4%d" % (bg)) 46 else: codes.append("10%d" % (bg)) 47 if bold: codes.append("1") 48 elif dim: codes.append("2") 49 else: codes.append("22") 50 return "\033[%sm" % (";".join(codes)) 51 52 53 class Field(): 54 def __init__(self, clazz, line, raw, blame): 55 self.clazz = clazz 56 self.line = line 57 self.raw = raw.strip(" {;") 58 self.blame = blame 59 60 raw = raw.split() 61 self.split = list(raw) 62 63 for r in ["field", "volatile", "transient", "public", "protected", "static", "final", "deprecated"]: 64 while r in raw: raw.remove(r) 65 66 self.typ = raw[0] 67 self.name = raw[1].strip(";") 68 if len(raw) >= 4 and raw[2] == "=": 69 self.value = raw[3].strip(';"') 70 else: 71 self.value = None 72 73 self.ident = self.raw.replace(" deprecated ", " ") 74 75 def __repr__(self): 76 return self.raw 77 78 79 class Method(): 80 def __init__(self, clazz, line, raw, blame): 81 self.clazz = clazz 82 self.line = line 83 self.raw = raw.strip(" {;") 84 self.blame = blame 85 86 # drop generics for now 87 raw = re.sub("<.+?>", "", raw) 88 89 raw = re.split("[\s(),;]+", raw) 90 for r in ["", ";"]: 91 while r in raw: raw.remove(r) 92 self.split = list(raw) 93 94 for r in ["method", "public", "protected", "static", "final", "deprecated", "abstract"]: 95 while r in raw: raw.remove(r) 96 97 self.typ = raw[0] 98 self.name = raw[1] 99 self.args = [] 100 for r in raw[2:]: 101 if r == "throws": break 102 self.args.append(r) 103 104 # identity for compat purposes 105 ident = self.raw 106 ident = ident.replace(" deprecated ", " ") 107 ident = ident.replace(" synchronized ", " ") 108 ident = re.sub("<.+?>", "", ident) 109 if " throws " in ident: 110 ident = ident[:ident.index(" throws ")] 111 self.ident = ident 112 113 def __repr__(self): 114 return self.raw 115 116 117 class Class(): 118 def __init__(self, pkg, line, raw, blame): 119 self.pkg = pkg 120 self.line = line 121 self.raw = raw.strip(" {;") 122 self.blame = blame 123 self.ctors = [] 124 self.fields = [] 125 self.methods = [] 126 127 raw = raw.split() 128 self.split = list(raw) 129 if "class" in raw: 130 self.fullname = raw[raw.index("class")+1] 131 elif "interface" in raw: 132 self.fullname = raw[raw.index("interface")+1] 133 else: 134 raise ValueError("Funky class type %s" % (self.raw)) 135 136 if "extends" in raw: 137 self.extends = raw[raw.index("extends")+1] 138 self.extends_path = self.extends.split(".") 139 else: 140 self.extends = None 141 self.extends_path = [] 142 143 self.fullname = self.pkg.name + "." + self.fullname 144 self.fullname_path = self.fullname.split(".") 145 146 self.name = self.fullname[self.fullname.rindex(".")+1:] 147 148 def __repr__(self): 149 return self.raw 150 151 152 class Package(): 153 def __init__(self, line, raw, blame): 154 self.line = line 155 self.raw = raw.strip(" {;") 156 self.blame = blame 157 158 raw = raw.split() 159 self.name = raw[raw.index("package")+1] 160 self.name_path = self.name.split(".") 161 162 def __repr__(self): 163 return self.raw 164 165 166 def _parse_stream(f, clazz_cb=None): 167 line = 0 168 api = {} 169 pkg = None 170 clazz = None 171 blame = None 172 173 re_blame = re.compile("^([a-z0-9]{7,}) \(<([^>]+)>.+?\) (.+?)$") 174 for raw in f: 175 line += 1 176 raw = raw.rstrip() 177 match = re_blame.match(raw) 178 if match is not None: 179 blame = match.groups()[0:2] 180 raw = match.groups()[2] 181 else: 182 blame = None 183 184 if raw.startswith("package"): 185 pkg = Package(line, raw, blame) 186 elif raw.startswith(" ") and raw.endswith("{"): 187 # When provided with class callback, we treat as incremental 188 # parse and don't build up entire API 189 if clazz and clazz_cb: 190 clazz_cb(clazz) 191 clazz = Class(pkg, line, raw, blame) 192 if not clazz_cb: 193 api[clazz.fullname] = clazz 194 elif raw.startswith(" ctor"): 195 clazz.ctors.append(Method(clazz, line, raw, blame)) 196 elif raw.startswith(" method"): 197 clazz.methods.append(Method(clazz, line, raw, blame)) 198 elif raw.startswith(" field"): 199 clazz.fields.append(Field(clazz, line, raw, blame)) 200 201 # Handle last trailing class 202 if clazz and clazz_cb: 203 clazz_cb(clazz) 204 205 return api 206 207 208 class Failure(): 209 def __init__(self, sig, clazz, detail, error, rule, msg): 210 self.sig = sig 211 self.error = error 212 self.rule = rule 213 self.msg = msg 214 215 if error: 216 self.head = "Error %s" % (rule) if rule else "Error" 217 dump = "%s%s:%s %s" % (format(fg=RED, bg=BLACK, bold=True), self.head, format(reset=True), msg) 218 else: 219 self.head = "Warning %s" % (rule) if rule else "Warning" 220 dump = "%s%s:%s %s" % (format(fg=YELLOW, bg=BLACK, bold=True), self.head, format(reset=True), msg) 221 222 self.line = clazz.line 223 blame = clazz.blame 224 if detail is not None: 225 dump += "\n in " + repr(detail) 226 self.line = detail.line 227 blame = detail.blame 228 dump += "\n in " + repr(clazz) 229 dump += "\n in " + repr(clazz.pkg) 230 dump += "\n at line " + repr(self.line) 231 if blame is not None: 232 dump += "\n last modified by %s in %s" % (blame[1], blame[0]) 233 234 self.dump = dump 235 236 def __repr__(self): 237 return self.dump 238 239 240 failures = {} 241 242 def _fail(clazz, detail, error, rule, msg): 243 """Records an API failure to be processed later.""" 244 global failures 245 246 sig = "%s-%s-%s" % (clazz.fullname, repr(detail), msg) 247 sig = sig.replace(" deprecated ", " ") 248 249 failures[sig] = Failure(sig, clazz, detail, error, rule, msg) 250 251 252 def warn(clazz, detail, rule, msg): 253 _fail(clazz, detail, False, rule, msg) 254 255 def error(clazz, detail, rule, msg): 256 _fail(clazz, detail, True, rule, msg) 257 258 259 def verify_constants(clazz): 260 """All static final constants must be FOO_NAME style.""" 261 if re.match("android\.R\.[a-z]+", clazz.fullname): return 262 263 for f in clazz.fields: 264 if "static" in f.split and "final" in f.split: 265 if re.match("[A-Z0-9_]+", f.name) is None: 266 error(clazz, f, "C2", "Constant field names must be FOO_NAME") 267 268 269 def verify_enums(clazz): 270 """Enums are bad, mmkay?""" 271 if "extends java.lang.Enum" in clazz.raw: 272 error(clazz, None, "F5", "Enums are not allowed") 273 274 275 def verify_class_names(clazz): 276 """Try catching malformed class names like myMtp or MTPUser.""" 277 if clazz.fullname.startswith("android.opengl"): return 278 if clazz.fullname.startswith("android.renderscript"): return 279 if re.match("android\.R\.[a-z]+", clazz.fullname): return 280 281 if re.search("[A-Z]{2,}", clazz.name) is not None: 282 warn(clazz, None, "S1", "Class names with acronyms should be Mtp not MTP") 283 if re.match("[^A-Z]", clazz.name): 284 error(clazz, None, "S1", "Class must start with uppercase char") 285 286 287 def verify_method_names(clazz): 288 """Try catching malformed method names, like Foo() or getMTU().""" 289 if clazz.fullname.startswith("android.opengl"): return 290 if clazz.fullname.startswith("android.renderscript"): return 291 if clazz.fullname == "android.system.OsConstants": return 292 293 for m in clazz.methods: 294 if re.search("[A-Z]{2,}", m.name) is not None: 295 warn(clazz, m, "S1", "Method names with acronyms should be getMtu() instead of getMTU()") 296 if re.match("[^a-z]", m.name): 297 error(clazz, m, "S1", "Method name must start with lowercase char") 298 299 300 def verify_callbacks(clazz): 301 """Verify Callback classes. 302 All callback classes must be abstract. 303 All methods must follow onFoo() naming style.""" 304 if clazz.fullname == "android.speech.tts.SynthesisCallback": return 305 306 if clazz.name.endswith("Callbacks"): 307 error(clazz, None, "L1", "Callback class names should be singular") 308 if clazz.name.endswith("Observer"): 309 warn(clazz, None, "L1", "Class should be named FooCallback") 310 311 if clazz.name.endswith("Callback"): 312 if "interface" in clazz.split: 313 error(clazz, None, "CL3", "Callbacks must be abstract class to enable extension in future API levels") 314 315 for m in clazz.methods: 316 if not re.match("on[A-Z][a-z]*", m.name): 317 error(clazz, m, "L1", "Callback method names must be onFoo() style") 318 319 320 def verify_listeners(clazz): 321 """Verify Listener classes. 322 All Listener classes must be interface. 323 All methods must follow onFoo() naming style. 324 If only a single method, it must match class name: 325 interface OnFooListener { void onFoo() }""" 326 327 if clazz.name.endswith("Listener"): 328 if " abstract class " in clazz.raw: 329 error(clazz, None, "L1", "Listeners should be an interface, or otherwise renamed Callback") 330 331 for m in clazz.methods: 332 if not re.match("on[A-Z][a-z]*", m.name): 333 error(clazz, m, "L1", "Listener method names must be onFoo() style") 334 335 if len(clazz.methods) == 1 and clazz.name.startswith("On"): 336 m = clazz.methods[0] 337 if (m.name + "Listener").lower() != clazz.name.lower(): 338 error(clazz, m, "L1", "Single listener method name must match class name") 339 340 341 def verify_actions(clazz): 342 """Verify intent actions. 343 All action names must be named ACTION_FOO. 344 All action values must be scoped by package and match name: 345 package android.foo { 346 String ACTION_BAR = "android.foo.action.BAR"; 347 }""" 348 for f in clazz.fields: 349 if f.value is None: continue 350 if f.name.startswith("EXTRA_"): continue 351 if f.name == "SERVICE_INTERFACE" or f.name == "PROVIDER_INTERFACE": continue 352 353 if "static" in f.split and "final" in f.split and f.typ == "java.lang.String": 354 if "_ACTION" in f.name or "ACTION_" in f.name or ".action." in f.value.lower(): 355 if not f.name.startswith("ACTION_"): 356 error(clazz, f, "C3", "Intent action constant name must be ACTION_FOO") 357 else: 358 if clazz.fullname == "android.content.Intent": 359 prefix = "android.intent.action" 360 elif clazz.fullname == "android.provider.Settings": 361 prefix = "android.settings" 362 elif clazz.fullname == "android.app.admin.DevicePolicyManager" or clazz.fullname == "android.app.admin.DeviceAdminReceiver": 363 prefix = "android.app.action" 364 else: 365 prefix = clazz.pkg.name + ".action" 366 expected = prefix + "." + f.name[7:] 367 if f.value != expected: 368 error(clazz, f, "C4", "Inconsistent action value; expected %s" % (expected)) 369 370 371 def verify_extras(clazz): 372 """Verify intent extras. 373 All extra names must be named EXTRA_FOO. 374 All extra values must be scoped by package and match name: 375 package android.foo { 376 String EXTRA_BAR = "android.foo.extra.BAR"; 377 }""" 378 if clazz.fullname == "android.app.Notification": return 379 if clazz.fullname == "android.appwidget.AppWidgetManager": return 380 381 for f in clazz.fields: 382 if f.value is None: continue 383 if f.name.startswith("ACTION_"): continue 384 385 if "static" in f.split and "final" in f.split and f.typ == "java.lang.String": 386 if "_EXTRA" in f.name or "EXTRA_" in f.name or ".extra" in f.value.lower(): 387 if not f.name.startswith("EXTRA_"): 388 error(clazz, f, "C3", "Intent extra must be EXTRA_FOO") 389 else: 390 if clazz.pkg.name == "android.content" and clazz.name == "Intent": 391 prefix = "android.intent.extra" 392 elif clazz.pkg.name == "android.app.admin": 393 prefix = "android.app.extra" 394 else: 395 prefix = clazz.pkg.name + ".extra" 396 expected = prefix + "." + f.name[6:] 397 if f.value != expected: 398 error(clazz, f, "C4", "Inconsistent extra value; expected %s" % (expected)) 399 400 401 def verify_equals(clazz): 402 """Verify that equals() and hashCode() must be overridden together.""" 403 methods = [ m.name for m in clazz.methods ] 404 eq = "equals" in methods 405 hc = "hashCode" in methods 406 if eq != hc: 407 error(clazz, None, "M8", "Must override both equals and hashCode; missing one") 408 409 410 def verify_parcelable(clazz): 411 """Verify that Parcelable objects aren't hiding required bits.""" 412 if "implements android.os.Parcelable" in clazz.raw: 413 creator = [ i for i in clazz.fields if i.name == "CREATOR" ] 414 write = [ i for i in clazz.methods if i.name == "writeToParcel" ] 415 describe = [ i for i in clazz.methods if i.name == "describeContents" ] 416 417 if len(creator) == 0 or len(write) == 0 or len(describe) == 0: 418 error(clazz, None, "FW3", "Parcelable requires CREATOR, writeToParcel, and describeContents; missing one") 419 420 421 def verify_protected(clazz): 422 """Verify that no protected methods or fields are allowed.""" 423 for m in clazz.methods: 424 if "protected" in m.split: 425 error(clazz, m, "M7", "Protected methods not allowed; must be public") 426 for f in clazz.fields: 427 if "protected" in f.split: 428 error(clazz, f, "M7", "Protected fields not allowed; must be public") 429 430 431 def verify_fields(clazz): 432 """Verify that all exposed fields are final. 433 Exposed fields must follow myName style. 434 Catch internal mFoo objects being exposed.""" 435 436 IGNORE_BARE_FIELDS = [ 437 "android.app.ActivityManager.RecentTaskInfo", 438 "android.app.Notification", 439 "android.content.pm.ActivityInfo", 440 "android.content.pm.ApplicationInfo", 441 "android.content.pm.FeatureGroupInfo", 442 "android.content.pm.InstrumentationInfo", 443 "android.content.pm.PackageInfo", 444 "android.content.pm.PackageItemInfo", 445 "android.os.Message", 446 "android.system.StructPollfd", 447 ] 448 449 for f in clazz.fields: 450 if not "final" in f.split: 451 if clazz.fullname in IGNORE_BARE_FIELDS: 452 pass 453 elif clazz.fullname.endswith("LayoutParams"): 454 pass 455 elif clazz.fullname.startswith("android.util.Mutable"): 456 pass 457 else: 458 error(clazz, f, "F2", "Bare fields must be marked final, or add accessors if mutable") 459 460 if not "static" in f.split: 461 if not re.match("[a-z]([a-zA-Z]+)?", f.name): 462 error(clazz, f, "S1", "Non-static fields must be named using myField style") 463 464 if re.match("[ms][A-Z]", f.name): 465 error(clazz, f, "F1", "Internal objects must not be exposed") 466 467 if re.match("[A-Z_]+", f.name): 468 if "static" not in f.split or "final" not in f.split: 469 error(clazz, f, "C2", "Constants must be marked static final") 470 471 472 def verify_register(clazz): 473 """Verify parity of registration methods. 474 Callback objects use register/unregister methods. 475 Listener objects use add/remove methods.""" 476 methods = [ m.name for m in clazz.methods ] 477 for m in clazz.methods: 478 if "Callback" in m.raw: 479 if m.name.startswith("register"): 480 other = "unregister" + m.name[8:] 481 if other not in methods: 482 error(clazz, m, "L2", "Missing unregister method") 483 if m.name.startswith("unregister"): 484 other = "register" + m.name[10:] 485 if other not in methods: 486 error(clazz, m, "L2", "Missing register method") 487 488 if m.name.startswith("add") or m.name.startswith("remove"): 489 error(clazz, m, "L3", "Callback methods should be named register/unregister") 490 491 if "Listener" in m.raw: 492 if m.name.startswith("add"): 493 other = "remove" + m.name[3:] 494 if other not in methods: 495 error(clazz, m, "L2", "Missing remove method") 496 if m.name.startswith("remove") and not m.name.startswith("removeAll"): 497 other = "add" + m.name[6:] 498 if other not in methods: 499 error(clazz, m, "L2", "Missing add method") 500 501 if m.name.startswith("register") or m.name.startswith("unregister"): 502 error(clazz, m, "L3", "Listener methods should be named add/remove") 503 504 505 def verify_sync(clazz): 506 """Verify synchronized methods aren't exposed.""" 507 for m in clazz.methods: 508 if "synchronized" in m.split: 509 error(clazz, m, "M5", "Internal locks must not be exposed") 510 511 512 def verify_intent_builder(clazz): 513 """Verify that Intent builders are createFooIntent() style.""" 514 if clazz.name == "Intent": return 515 516 for m in clazz.methods: 517 if m.typ == "android.content.Intent": 518 if m.name.startswith("create") and m.name.endswith("Intent"): 519 pass 520 else: 521 warn(clazz, m, "FW1", "Methods creating an Intent should be named createFooIntent()") 522 523 524 def verify_helper_classes(clazz): 525 """Verify that helper classes are named consistently with what they extend. 526 All developer extendable methods should be named onFoo().""" 527 test_methods = False 528 if "extends android.app.Service" in clazz.raw: 529 test_methods = True 530 if not clazz.name.endswith("Service"): 531 error(clazz, None, "CL4", "Inconsistent class name; should be FooService") 532 533 found = False 534 for f in clazz.fields: 535 if f.name == "SERVICE_INTERFACE": 536 found = True 537 if f.value != clazz.fullname: 538 error(clazz, f, "C4", "Inconsistent interface constant; expected %s" % (clazz.fullname)) 539 540 if "extends android.content.ContentProvider" in clazz.raw: 541 test_methods = True 542 if not clazz.name.endswith("Provider"): 543 error(clazz, None, "CL4", "Inconsistent class name; should be FooProvider") 544 545 found = False 546 for f in clazz.fields: 547 if f.name == "PROVIDER_INTERFACE": 548 found = True 549 if f.value != clazz.fullname: 550 error(clazz, f, "C4", "Inconsistent interface constant; expected %s" % (clazz.fullname)) 551 552 if "extends android.content.BroadcastReceiver" in clazz.raw: 553 test_methods = True 554 if not clazz.name.endswith("Receiver"): 555 error(clazz, None, "CL4", "Inconsistent class name; should be FooReceiver") 556 557 if "extends android.app.Activity" in clazz.raw: 558 test_methods = True 559 if not clazz.name.endswith("Activity"): 560 error(clazz, None, "CL4", "Inconsistent class name; should be FooActivity") 561 562 if test_methods: 563 for m in clazz.methods: 564 if "final" in m.split: continue 565 if not re.match("on[A-Z]", m.name): 566 if "abstract" in m.split: 567 warn(clazz, m, None, "Methods implemented by developers should be named onFoo()") 568 else: 569 warn(clazz, m, None, "If implemented by developer, should be named onFoo(); otherwise consider marking final") 570 571 572 def verify_builder(clazz): 573 """Verify builder classes. 574 Methods should return the builder to enable chaining.""" 575 if " extends " in clazz.raw: return 576 if not clazz.name.endswith("Builder"): return 577 578 if clazz.name != "Builder": 579 warn(clazz, None, None, "Builder should be defined as inner class") 580 581 has_build = False 582 for m in clazz.methods: 583 if m.name == "build": 584 has_build = True 585 continue 586 587 if m.name.startswith("get"): continue 588 if m.name.startswith("clear"): continue 589 590 if m.name.startswith("with"): 591 warn(clazz, m, None, "Builder methods names should use setFoo() style") 592 593 if m.name.startswith("set"): 594 if not m.typ.endswith(clazz.fullname): 595 warn(clazz, m, "M4", "Methods must return the builder object") 596 597 if not has_build: 598 warn(clazz, None, None, "Missing build() method") 599 600 601 def verify_aidl(clazz): 602 """Catch people exposing raw AIDL.""" 603 if "extends android.os.Binder" in clazz.raw or "implements android.os.IInterface" in clazz.raw: 604 error(clazz, None, None, "Raw AIDL interfaces must not be exposed") 605 606 607 def verify_internal(clazz): 608 """Catch people exposing internal classes.""" 609 if clazz.pkg.name.startswith("com.android"): 610 error(clazz, None, None, "Internal classes must not be exposed") 611 612 613 def verify_layering(clazz): 614 """Catch package layering violations. 615 For example, something in android.os depending on android.app.""" 616 ranking = [ 617 ["android.service","android.accessibilityservice","android.inputmethodservice","android.printservice","android.appwidget","android.webkit","android.preference","android.gesture","android.print"], 618 "android.app", 619 "android.widget", 620 "android.view", 621 "android.animation", 622 "android.provider", 623 ["android.content","android.graphics.drawable"], 624 "android.database", 625 "android.graphics", 626 "android.text", 627 "android.os", 628 "android.util" 629 ] 630 631 def rank(p): 632 for i in range(len(ranking)): 633 if isinstance(ranking[i], list): 634 for j in ranking[i]: 635 if p.startswith(j): return i 636 else: 637 if p.startswith(ranking[i]): return i 638 639 cr = rank(clazz.pkg.name) 640 if cr is None: return 641 642 for f in clazz.fields: 643 ir = rank(f.typ) 644 if ir and ir < cr: 645 warn(clazz, f, "FW6", "Field type violates package layering") 646 647 for m in clazz.methods: 648 ir = rank(m.typ) 649 if ir and ir < cr: 650 warn(clazz, m, "FW6", "Method return type violates package layering") 651 for arg in m.args: 652 ir = rank(arg) 653 if ir and ir < cr: 654 warn(clazz, m, "FW6", "Method argument type violates package layering") 655 656 657 def verify_boolean(clazz): 658 """Verifies that boolean accessors are named correctly. 659 For example, hasFoo() and setHasFoo().""" 660 661 def is_get(m): return len(m.args) == 0 and m.typ == "boolean" 662 def is_set(m): return len(m.args) == 1 and m.args[0] == "boolean" 663 664 gets = [ m for m in clazz.methods if is_get(m) ] 665 sets = [ m for m in clazz.methods if is_set(m) ] 666 667 def error_if_exists(methods, trigger, expected, actual): 668 for m in methods: 669 if m.name == actual: 670 error(clazz, m, "M6", "Symmetric method for %s must be named %s" % (trigger, expected)) 671 672 for m in clazz.methods: 673 if is_get(m): 674 if re.match("is[A-Z]", m.name): 675 target = m.name[2:] 676 expected = "setIs" + target 677 error_if_exists(sets, m.name, expected, "setHas" + target) 678 elif re.match("has[A-Z]", m.name): 679 target = m.name[3:] 680 expected = "setHas" + target 681 error_if_exists(sets, m.name, expected, "setIs" + target) 682 error_if_exists(sets, m.name, expected, "set" + target) 683 elif re.match("get[A-Z]", m.name): 684 target = m.name[3:] 685 expected = "set" + target 686 error_if_exists(sets, m.name, expected, "setIs" + target) 687 error_if_exists(sets, m.name, expected, "setHas" + target) 688 689 if is_set(m): 690 if re.match("set[A-Z]", m.name): 691 target = m.name[3:] 692 expected = "get" + target 693 error_if_exists(sets, m.name, expected, "is" + target) 694 error_if_exists(sets, m.name, expected, "has" + target) 695 696 697 def verify_collections(clazz): 698 """Verifies that collection types are interfaces.""" 699 if clazz.fullname == "android.os.Bundle": return 700 701 bad = ["java.util.Vector", "java.util.LinkedList", "java.util.ArrayList", "java.util.Stack", 702 "java.util.HashMap", "java.util.HashSet", "android.util.ArraySet", "android.util.ArrayMap"] 703 for m in clazz.methods: 704 if m.typ in bad: 705 error(clazz, m, "CL2", "Return type is concrete collection; must be higher-level interface") 706 for arg in m.args: 707 if arg in bad: 708 error(clazz, m, "CL2", "Argument is concrete collection; must be higher-level interface") 709 710 711 def verify_flags(clazz): 712 """Verifies that flags are non-overlapping.""" 713 known = collections.defaultdict(int) 714 for f in clazz.fields: 715 if "FLAG_" in f.name: 716 try: 717 val = int(f.value) 718 except: 719 continue 720 721 scope = f.name[0:f.name.index("FLAG_")] 722 if val & known[scope]: 723 warn(clazz, f, "C1", "Found overlapping flag constant value") 724 known[scope] |= val 725 726 727 def verify_exception(clazz): 728 """Verifies that methods don't throw generic exceptions.""" 729 for m in clazz.methods: 730 if "throws java.lang.Exception" in m.raw or "throws java.lang.Throwable" in m.raw or "throws java.lang.Error" in m.raw: 731 error(clazz, m, "S1", "Methods must not throw generic exceptions") 732 733 734 def verify_google(clazz): 735 """Verifies that APIs never reference Google.""" 736 737 if re.search("google", clazz.raw, re.IGNORECASE): 738 error(clazz, None, None, "Must never reference Google") 739 740 test = [] 741 test.extend(clazz.ctors) 742 test.extend(clazz.fields) 743 test.extend(clazz.methods) 744 745 for t in test: 746 if re.search("google", t.raw, re.IGNORECASE): 747 error(clazz, t, None, "Must never reference Google") 748 749 750 def verify_bitset(clazz): 751 """Verifies that we avoid using heavy BitSet.""" 752 753 for f in clazz.fields: 754 if f.typ == "java.util.BitSet": 755 error(clazz, f, None, "Field type must not be heavy BitSet") 756 757 for m in clazz.methods: 758 if m.typ == "java.util.BitSet": 759 error(clazz, m, None, "Return type must not be heavy BitSet") 760 for arg in m.args: 761 if arg == "java.util.BitSet": 762 error(clazz, m, None, "Argument type must not be heavy BitSet") 763 764 765 def verify_manager(clazz): 766 """Verifies that FooManager is only obtained from Context.""" 767 768 if not clazz.name.endswith("Manager"): return 769 770 for c in clazz.ctors: 771 error(clazz, c, None, "Managers must always be obtained from Context; no direct constructors") 772 773 774 def verify_boxed(clazz): 775 """Verifies that methods avoid boxed primitives.""" 776 777 boxed = ["java.lang.Number","java.lang.Byte","java.lang.Double","java.lang.Float","java.lang.Integer","java.lang.Long","java.lang.Short"] 778 779 for c in clazz.ctors: 780 for arg in c.args: 781 if arg in boxed: 782 error(clazz, c, "M11", "Must avoid boxed primitives") 783 784 for f in clazz.fields: 785 if f.typ in boxed: 786 error(clazz, f, "M11", "Must avoid boxed primitives") 787 788 for m in clazz.methods: 789 if m.typ in boxed: 790 error(clazz, m, "M11", "Must avoid boxed primitives") 791 for arg in m.args: 792 if arg in boxed: 793 error(clazz, m, "M11", "Must avoid boxed primitives") 794 795 796 def verify_static_utils(clazz): 797 """Verifies that helper classes can't be constructed.""" 798 if clazz.fullname.startswith("android.opengl"): return 799 if re.match("android\.R\.[a-z]+", clazz.fullname): return 800 801 if len(clazz.fields) > 0: return 802 if len(clazz.methods) == 0: return 803 804 for m in clazz.methods: 805 if "static" not in m.split: 806 return 807 808 # At this point, we have no fields, and all methods are static 809 if len(clazz.ctors) > 0: 810 error(clazz, None, None, "Fully-static utility classes must not have constructor") 811 812 813 def verify_overload_args(clazz): 814 """Verifies that method overloads add new arguments at the end.""" 815 if clazz.fullname.startswith("android.opengl"): return 816 817 overloads = collections.defaultdict(list) 818 for m in clazz.methods: 819 if "deprecated" in m.split: continue 820 overloads[m.name].append(m) 821 822 for name, methods in overloads.items(): 823 if len(methods) <= 1: continue 824 825 # Look for arguments common across all overloads 826 def cluster(args): 827 count = collections.defaultdict(int) 828 res = set() 829 for i in range(len(args)): 830 a = args[i] 831 res.add("%s#%d" % (a, count[a])) 832 count[a] += 1 833 return res 834 835 common_args = cluster(methods[0].args) 836 for m in methods: 837 common_args = common_args & cluster(m.args) 838 839 if len(common_args) == 0: continue 840 841 # Require that all common arguments are present at start of signature 842 locked_sig = None 843 for m in methods: 844 sig = m.args[0:len(common_args)] 845 if not common_args.issubset(cluster(sig)): 846 warn(clazz, m, "M2", "Expected common arguments [%s] at beginning of overloaded method" % (", ".join(common_args))) 847 elif not locked_sig: 848 locked_sig = sig 849 elif locked_sig != sig: 850 error(clazz, m, "M2", "Expected consistent argument ordering between overloads: %s..." % (", ".join(locked_sig))) 851 852 853 def verify_callback_handlers(clazz): 854 """Verifies that methods adding listener/callback have overload 855 for specifying delivery thread.""" 856 857 # Ignore UI packages which assume main thread 858 skip = [ 859 "animation", 860 "view", 861 "graphics", 862 "transition", 863 "widget", 864 "webkit", 865 ] 866 for s in skip: 867 if s in clazz.pkg.name_path: return 868 if s in clazz.extends_path: return 869 870 # Ignore UI classes which assume main thread 871 if "app" in clazz.pkg.name_path or "app" in clazz.extends_path: 872 for s in ["ActionBar","Dialog","Application","Activity","Fragment","Loader"]: 873 if s in clazz.fullname: return 874 if "content" in clazz.pkg.name_path or "content" in clazz.extends_path: 875 for s in ["Loader"]: 876 if s in clazz.fullname: return 877 878 found = {} 879 by_name = collections.defaultdict(list) 880 for m in clazz.methods: 881 if m.name.startswith("unregister"): continue 882 if m.name.startswith("remove"): continue 883 if re.match("on[A-Z]+", m.name): continue 884 885 by_name[m.name].append(m) 886 887 for a in m.args: 888 if a.endswith("Listener") or a.endswith("Callback") or a.endswith("Callbacks"): 889 found[m.name] = m 890 891 for f in found.values(): 892 takes_handler = False 893 for m in by_name[f.name]: 894 if "android.os.Handler" in m.args: 895 takes_handler = True 896 if not takes_handler: 897 warn(clazz, f, "L1", "Registration methods should have overload that accepts delivery Handler") 898 899 900 def verify_context_first(clazz): 901 """Verifies that methods accepting a Context keep it the first argument.""" 902 examine = clazz.ctors + clazz.methods 903 for m in examine: 904 if len(m.args) > 1 and m.args[0] != "android.content.Context": 905 if "android.content.Context" in m.args[1:]: 906 error(clazz, m, "M3", "Context is distinct, so it must be the first argument") 907 908 909 def verify_listener_last(clazz): 910 """Verifies that methods accepting a Listener or Callback keep them as last arguments.""" 911 examine = clazz.ctors + clazz.methods 912 for m in examine: 913 if "Listener" in m.name or "Callback" in m.name: continue 914 found = False 915 for a in m.args: 916 if a.endswith("Callback") or a.endswith("Callbacks") or a.endswith("Listener"): 917 found = True 918 elif found and a != "android.os.Handler": 919 warn(clazz, m, "M3", "Listeners should always be at end of argument list") 920 921 922 def verify_resource_names(clazz): 923 """Verifies that resource names have consistent case.""" 924 if not re.match("android\.R\.[a-z]+", clazz.fullname): return 925 926 # Resources defined by files are foo_bar_baz 927 if clazz.name in ["anim","animator","color","dimen","drawable","interpolator","layout","transition","menu","mipmap","string","plurals","raw","xml"]: 928 for f in clazz.fields: 929 if re.match("[a-z1-9_]+$", f.name): continue 930 error(clazz, f, None, "Expected resource name in this class to be foo_bar_baz style") 931 932 # Resources defined inside files are fooBarBaz 933 if clazz.name in ["array","attr","id","bool","fraction","integer"]: 934 for f in clazz.fields: 935 if re.match("config_[a-z][a-zA-Z1-9]*$", f.name): continue 936 if re.match("layout_[a-z][a-zA-Z1-9]*$", f.name): continue 937 if re.match("state_[a-z_]*$", f.name): continue 938 939 if re.match("[a-z][a-zA-Z1-9]*$", f.name): continue 940 error(clazz, f, "C7", "Expected resource name in this class to be fooBarBaz style") 941 942 # Styles are FooBar_Baz 943 if clazz.name in ["style"]: 944 for f in clazz.fields: 945 if re.match("[A-Z][A-Za-z1-9]+(_[A-Z][A-Za-z1-9]+?)*$", f.name): continue 946 error(clazz, f, "C7", "Expected resource name in this class to be FooBar_Baz style") 947 948 949 def examine_clazz(clazz): 950 """Find all style issues in the given class.""" 951 if clazz.pkg.name.startswith("java"): return 952 if clazz.pkg.name.startswith("junit"): return 953 if clazz.pkg.name.startswith("org.apache"): return 954 if clazz.pkg.name.startswith("org.xml"): return 955 if clazz.pkg.name.startswith("org.json"): return 956 if clazz.pkg.name.startswith("org.w3c"): return 957 958 verify_constants(clazz) 959 verify_enums(clazz) 960 verify_class_names(clazz) 961 verify_method_names(clazz) 962 verify_callbacks(clazz) 963 verify_listeners(clazz) 964 verify_actions(clazz) 965 verify_extras(clazz) 966 verify_equals(clazz) 967 verify_parcelable(clazz) 968 verify_protected(clazz) 969 verify_fields(clazz) 970 verify_register(clazz) 971 verify_sync(clazz) 972 verify_intent_builder(clazz) 973 verify_helper_classes(clazz) 974 verify_builder(clazz) 975 verify_aidl(clazz) 976 verify_internal(clazz) 977 verify_layering(clazz) 978 verify_boolean(clazz) 979 verify_collections(clazz) 980 verify_flags(clazz) 981 verify_exception(clazz) 982 if not ALLOW_GOOGLE: verify_google(clazz) 983 verify_bitset(clazz) 984 verify_manager(clazz) 985 verify_boxed(clazz) 986 verify_static_utils(clazz) 987 verify_overload_args(clazz) 988 verify_callback_handlers(clazz) 989 verify_context_first(clazz) 990 verify_listener_last(clazz) 991 verify_resource_names(clazz) 992 993 994 def examine_stream(stream): 995 """Find all style issues in the given API stream.""" 996 global failures 997 failures = {} 998 _parse_stream(stream, examine_clazz) 999 return failures 1000 1001 1002 def examine_api(api): 1003 """Find all style issues in the given parsed API.""" 1004 global failures 1005 failures = {} 1006 for key in sorted(api.keys()): 1007 examine_clazz(api[key]) 1008 return failures 1009 1010 1011 def verify_compat(cur, prev): 1012 """Find any incompatible API changes between two levels.""" 1013 global failures 1014 1015 def class_exists(api, test): 1016 return test.fullname in api 1017 1018 def ctor_exists(api, clazz, test): 1019 for m in clazz.ctors: 1020 if m.ident == test.ident: return True 1021 return False 1022 1023 def all_methods(api, clazz): 1024 methods = list(clazz.methods) 1025 if clazz.extends is not None: 1026 methods.extend(all_methods(api, api[clazz.extends])) 1027 return methods 1028 1029 def method_exists(api, clazz, test): 1030 methods = all_methods(api, clazz) 1031 for m in methods: 1032 if m.ident == test.ident: return True 1033 return False 1034 1035 def field_exists(api, clazz, test): 1036 for f in clazz.fields: 1037 if f.ident == test.ident: return True 1038 return False 1039 1040 failures = {} 1041 for key in sorted(prev.keys()): 1042 prev_clazz = prev[key] 1043 1044 if not class_exists(cur, prev_clazz): 1045 error(prev_clazz, None, None, "Class removed or incompatible change") 1046 continue 1047 1048 cur_clazz = cur[key] 1049 1050 for test in prev_clazz.ctors: 1051 if not ctor_exists(cur, cur_clazz, test): 1052 error(prev_clazz, prev_ctor, None, "Constructor removed or incompatible change") 1053 1054 methods = all_methods(prev, prev_clazz) 1055 for test in methods: 1056 if not method_exists(cur, cur_clazz, test): 1057 error(prev_clazz, test, None, "Method removed or incompatible change") 1058 1059 for test in prev_clazz.fields: 1060 if not field_exists(cur, cur_clazz, test): 1061 error(prev_clazz, test, None, "Field removed or incompatible change") 1062 1063 return failures 1064 1065 1066 if __name__ == "__main__": 1067 parser = argparse.ArgumentParser(description="Enforces common Android public API design \ 1068 patterns. It ignores lint messages from a previous API level, if provided.") 1069 parser.add_argument("current.txt", type=argparse.FileType('r'), help="current.txt") 1070 parser.add_argument("previous.txt", nargs='?', type=argparse.FileType('r'), default=None, 1071 help="previous.txt") 1072 parser.add_argument("--no-color", action='store_const', const=True, 1073 help="Disable terminal colors") 1074 parser.add_argument("--allow-google", action='store_const', const=True, 1075 help="Allow references to Google") 1076 args = vars(parser.parse_args()) 1077 1078 if args['no_color']: 1079 USE_COLOR = False 1080 1081 if args['allow_google']: 1082 ALLOW_GOOGLE = True 1083 1084 current_file = args['current.txt'] 1085 previous_file = args['previous.txt'] 1086 1087 with current_file as f: 1088 cur_fail = examine_stream(f) 1089 if not previous_file is None: 1090 with previous_file as f: 1091 prev_fail = examine_stream(f) 1092 1093 # ignore errors from previous API level 1094 for p in prev_fail: 1095 if p in cur_fail: 1096 del cur_fail[p] 1097 1098 """ 1099 # NOTE: disabled because of memory pressure 1100 # look for compatibility issues 1101 compat_fail = verify_compat(cur, prev) 1102 1103 print "%s API compatibility issues %s\n" % ((format(fg=WHITE, bg=BLUE, bold=True), format(reset=True))) 1104 for f in sorted(compat_fail): 1105 print compat_fail[f] 1106 print 1107 """ 1108 1109 print "%s API style issues %s\n" % ((format(fg=WHITE, bg=BLUE, bold=True), format(reset=True))) 1110 for f in sorted(cur_fail): 1111 print cur_fail[f] 1112 print 1113
