diff options
3 files changed, 60 insertions, 56 deletions
diff --git a/site/versions/master/docs/skylark/concepts.md b/site/versions/master/docs/skylark/concepts.md index 20ebb72ca2..ca5d69db05 100644 --- a/site/versions/master/docs/skylark/concepts.md +++ b/site/versions/master/docs/skylark/concepts.md @@ -204,44 +204,45 @@ The following Python features are not supported: The following items are upcoming changes. -* Comprehensions currently "leak" the values of their loop variables into the - surrounding scope (Python 2 semantics). This will be changed so that - comprehension variables are local (Python 3 semantics). - -* Previously dictionaries were guaranteed to use sorted order for their keys. - Going forward, there is no guarantee on order besides that it is - deterministic. As an implementation matter, some kinds of dictionaries may - continue to use sorted order while others may use insertion order. - -* The `+=` operator and similar operators are currently syntactic sugar; - `x += y` is the same as `x = x + y`. This will change to follow Python - semantics, so that for mutable collection datatypes, `x += y` will be a - mutation to the value of `x` rather than a rebinding of the variable `x` - itself to a new value. E.g. for lists, `x += y` will be the same as - `x.extend(y)`. - -* The `+` operator is defined for dictionaries, returning an immutable - concatenated dictionary created from the entries of the original - dictionaries. This will be going away. The same result can be achieved using - `dict(a.items() + b.items())`. Likewise, there is a `+` operator for sets that - will be going away; users should use `|` instead. - -* The order comparison operators (<, <=, >=, >) are currently defined across - different types of values, e.g., you can write `5 < 'foo'`. This will be an - error, just like in Python 3. Note that this means you will be unable to - sort lists that contain mixed types of values. - -* The structure of the set that you get back from using the `+` or `|` operator - is changing. Previously `a + b`, where `a` is a set, would include as its - direct items all of `a`'s direct items. Under the upcoming way, the result - will only include `a` as a single transitive entity. This will alter the - visible iteration order of the returned set. Most notably, - `set([1, 2]) + set([3, 4] + set([5, 6])` will return elements in the order - `1 2 3 4 5 6` instead of `3 4 5 6 1 2`. This change is associated with a fix - that improves set union to be O(1) time. - -* The set datatype will be renamed in order to avoid confusion with Python's - set datatype, which behaves very differently. +* Comprehensions currently "leak" the values of their loop variables into the + surrounding scope (Python 2 semantics). This will be changed so that + comprehension variables are local (Python 3 semantics). + +* Previously dictionaries were guaranteed to use sorted order for their keys. + Going forward, there is no guarantee on order besides that it is + deterministic. As an implementation matter, some kinds of dictionaries may + continue to use sorted order while others may use insertion order. + +* The `+=` operator and similar operators are currently syntactic sugar; `x += + y` is the same as `x = x + y`. This will change to follow Python semantics, + so that for mutable collection datatypes, `x += y` will be a mutation to the + value of `x` rather than a rebinding of the variable `x` itself to a new + value. E.g. for lists, `x += y` will be the same as `x.extend(y)`. + +* The "set" datatype is being renamed to "depset" in order to avoid confusion + with Python's sets, which behave very differently. + +* The `+` operator is defined for dictionaries, returning an immutable + concatenated dictionary created from the entries of the original + dictionaries. This will be going away. The same result can be achieved using + `dict(a.items() + b.items())`. + +* The `|` operator is defined for depsets as a synonym for `+`. This will be + going away; use `+` instead. + +* The order comparison operators (<, <=, >=, >) are currently defined across + different types of values, e.g., you can write `5 < 'foo'`. This will be an + error, just like in Python 3. Note that this means you will be unable to + sort lists that contain mixed types of values. + +* The structure of the set that you get back from using the `+` or `|` + operator is changing. Previously `a + b`, where `a` is a set, would include + as its direct items all of `a`'s direct items. Under the upcoming way, the + result will only include `a` as a single transitive entity. This will alter + the visible iteration order of the returned set. Most notably, `set([1, + 2]) + set([3, 4] + set([5, 6])` will return elements in the order `1 2 3 4 5 + 6` instead of `3 4 5 6 1 2`. This change is associated with a fix that + improves set union to be O(1) time. These changes concern the `load()` syntax in particular. diff --git a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java index 0dddafb731..b2143df77a 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java @@ -1720,9 +1720,12 @@ public class MethodLibrary { returnType = SkylarkDict.class, doc = "Creates a <a href=\"dict.html\">dictionary</a> from an optional positional " - + "argument and an optional set of keyword arguments. Values from the keyword " - + "argument will overwrite values from the positional argument if a key appears " - + "multiple times.", + + "argument and an optional set of keyword arguments. In the case where the same key " + + "is given multiple times, the last value will be used. Entries supplied via keyword " + + "arguments are considered to come after entries supplied via the positional " + + "argument. Note that the iteration order for dictionaries is deterministic but " + + "unspecified, and not necessarily related to the order in which keys are given to " + + "this function.", parameters = { @Param( name = "args", @@ -1730,7 +1733,7 @@ public class MethodLibrary { defaultValue = "[]", doc = "Either a dictionary or a list of entries. Entries must be tuples or lists with " - + "exactly two elements: key, value" + + "exactly two elements: key, value." ), }, extraKeywords = @Param(name = "kwargs", doc = "Dictionary of additional entries."), diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java index ad0a97dfe7..d622a7ccce 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java @@ -27,22 +27,22 @@ import javax.annotation.Nullable; */ @SkylarkModule(name = "dict", category = SkylarkModuleCategory.BUILTIN, - doc = "A language built-in type to support dicts. " - + "Example of dict literal:<br>" + doc = "A language built-in type representating a dictionary (associative mapping). " + + "Dictionaries may be constructed with a special literal syntax:<br>" + "<pre class=\"language-python\">d = {\"a\": 2, \"b\": 5}</pre>" - + "Use brackets to access elements:<br>" + + "Use square brackets to access elements:<br>" + "<pre class=\"language-python\">e = d[\"a\"] # e == 2</pre>" - + "Dicts support the <code>+</code> operator to concatenate two dicts. In case of multiple " - + "keys the second one overrides the first one. Examples:<br>" - + "<pre class=\"language-python\">" - + "d = {\"a\" : 1} + {\"b\" : 2} # d == {\"a\" : 1, \"b\" : 2}\n" - + "d += {\"c\" : 3} # d == {\"a\" : 1, \"b\" : 2, \"c\" : 3}\n" - + "d = d + {\"c\" : 5} # d == {\"a\" : 1, \"b\" : 2, \"c\" : 5}</pre>" - + "Iterating on a dict is equivalent to iterating on its keys (order is not specified).<br>" - + "Dicts support the <code>in</code> operator, testing membership in the keyset of the dict. " - + "Example:<br>" - + "<pre class=\"language-python\">\"a\" in {\"a\" : 2, \"b\" : 5} # evaluates as True" - + "</pre>") + + "Like lists, they can also be constructed using a comprehension syntax:<br>" + + "<pre class=\"language-python\">d = {i: 2*i for i in range(20)}\n" + + "e = d[8] # e == 16</pre>" + + "See also the <a href=\"globals.html#dict\">dict()</a> constructor function. " + + "<p>Iterating over a dict is equivalent to iterating over its keys. The <code>in</code> " + + "operator tests for membership in the keyset of the dict.<br>" + + "<pre class=\"language-python\">\"a\" in {\"a\" : 2, \"b\" : 5} # evaluates as True</pre>" + + "The iteration order for a dict is deterministic but not specified. When constructing a dict " + + "using any of the above methods, if there are two identical keys with conflicting values " + + "then the last value takes precedence." +) public final class SkylarkDict<K, V> extends MutableMap<K, V> implements Map<K, V>, SkylarkIndexable { |