1

"""

     2

    Tree-based URL mapping

     3

"""

     4

     5

import re

     6

import os.path

     7

     8

from qmsk.web import handler

     9

    10

class URLError (Exception) :

    11

    """

    12

        Error with an URL definition

    13

    """

    14

    15

    pass

    16

    17

class LabelValue (object) :

    18

    """

    19

        Represents the value of a ValueLabel... love these names

    20

    """

    21

    22

    def __init__ (self, label, value, is_default) :

    23

        """

    24

            Just store

    25

        """

    26

    27

        self.label = label

    28

        self.value = value

    29

        self.is_default = is_default

    30

    31

    def __str__ (self) :

    32

        return "%s%s" % (self.label.key, "=%r" % (self.value, ) if not self.is_default else '')

    33

    34

    def __repr__ (self) :

    35

        return "<%s>" % self

    36

    37

class Label (object) :

    38

    """

    39

        Base class for URL labels (i.e. the segments of the URL between /s)

    40

    """

    41

    42

    @staticmethod

    43

    def parse (mask, defaults, config) :

    44

        """

    45

            Parse the given label-segment, and return a *Label instance. Config is the URLConfig to use

    46

        """

    47

    48

        # empty?

    49

        if not mask :

    50

            return EmptyLabel()

    51

    52

        # simple value?

    53

        match = SimpleValueLabel.EXPR.match(mask)

    54

    55

        if match :

    56

            # key

    57

            key = match.group('key')

    58

    59

            # type

    60

            type_name = match.group("type")

    61

    62

            # lookup type, None -> default

    63

            type = config.get_type(type_name)

    64

    65

            # defaults?

    66

            default = defaults.get(key)

    67

    68

            if not default :

    69

                default = match.group('default')

    70

    71

                if default :

    72

                    # apply type to default

    73

                    default = type.parse(default)

    74

    75

            # build

    76

            return SimpleValueLabel(key, type_name, type, default)

    77

    78

        # static?

    79

        match = StaticLabel.EXPR.match(mask)

    80

    81

        if match :

    82

            return StaticLabel(match.group('name'))

    83

    84

        # invalid

    85

        raise URLError("Invalid label: %r" % (mask, ))

    86

    87

    def match (self, value=None) :

    88

        """

    89

            Match this label against the given value, returning either True to match without a value, a LabelValue

    90

            object, or boolean false to not match.

    91

    92

            If value is None, this means that only a default value should be returned.

    93

        """

    94

    95

        abstract

    96

    97

    def build (self, value_dict) :

    98

        """

    99

            Return a string representing this label, using the values in the given value_dict if needed

   100

        """

   101

   102

        abstract

   103

   104

    def build_default (self, value_dict) :

   105

        """

   106

            Return an (is_default, value) tuple

   107

        """

   108

   109

        abstract

   110

   111

   112

class EmptyLabel (Label) :

   113

    """

   114

        An empty label, i.e. just a slash in the URL

   115

    """

   116

   117

    def __eq__ (self, other) :

   118

        """

   119

            Just compares type

   120

        """

   121

   122

        return isinstance(other, EmptyLabel)

   123

   124

    def match (self, value=None) :

   125

        """

   126

            Match empty string -> True

   127

        """

   128

   129

        # no default

   130

        if value is None :

   131

            return False

   132

   133

        # only empty segments

   134

        if value == '' :

   135

            return True

   136

   137

    def build (self, values) :

   138

        return ''

   139

   140

    def build_default (self, values) :

   141

        return (False, '')

   142

   143

    def __str__ (self) :

   144

        return ''

   145

   146

class StaticLabel (Label) :

   147

    """

   148

        A simple literal Label, used for fixed terms in the URL

   149

    """

   150

   151

    EXPR = re.compile(r'^(?P<name>[a-zA-Z0-9_.-]+)$')

   152

   153

    def __init__ (self, name) :

   154

        """

   155

            The given name is the literal name of this label

   156

        """

   157

   158

        self.name = name

   159

   160

    def __eq__ (self, other) :

   161

        """

   162

            Compares names

   163

        """

   164

   165

        return isinstance(other, StaticLabel) and self.name == other.name

   166

   167

    def match (self, value=None) :

   168

        """

   169

            Match exactly -> True

   170

        """

   171

   172

        # no defaults

   173

        if value is None :

   174

            return False

   175

   176

        # match name

   177

        if value == self.name :

   178

            return True

   179

   180

    def build (self, values) :

   181

        return self.name

   182

   183

    def build_default (self, values) :

   184

        return (False, self.name)

   185

   186

    def __str__ (self) :

   187

        return self.name

   188

   189

class ValueLabel (Label) :

   190

    """

   191

        A label with a key and a value

   192

   193

        XXX: do we even need this?

   194

    """

   195

   196

    def __init__ (self, key, default) :

   197

        """

   198

            Set the key and default value. Default value may be None if there is no default value defined

   199

        """

   200

   201

        self.key = key

   202

        self.default = default

   203

   204

    def __eq__ (self, other) :

   205

        """

   206

            Compares keys

   207

        """

   208

   209

        return isinstance(other, ValueLabel) and self.key == other.key

   210

   211

    def build (self, values) :

   212

        """

   213

            Return either the assigned value from values, our default value, or raise an error

   214

        """

   215

   216

        # just proxy to build_default

   217

        return self.build_default(values)[1]

   218

   219

    def build_default (self, values) :

   220

        """

   221

            Check if we have a value in values, and return based on that

   222

        """

   223

   224

        # state

   225

        is_default = False

   226

   227

        # value given?

   228

        if self.key not in values or values[self.key] is None :

   229

            # error on missing non-default

   230

            if self.default is None :

   231

                raise URLError("No value given for label %r" % (self.key, ))

   232

   233

            # use default

   234

            else :

   235

                is_default = True

   236

                value = self.default

   237

   238

        else :

   239

            # lookup the value obj to use

   240

            value = values[self.key]

   241

   242

        # convert value back to str

   243

        value = self.type.build(value)

   244

   245

        # return

   246

        return (is_default, value)

   247

   248

class SimpleValueLabel (ValueLabel) :

   249

    """

   250

        A label that has a name and a simple string value

   251

    """

   252

   253

    EXPR = re.compile(r'^\{(?P<key>[a-zA-Z_][a-zA-Z0-9_]*)(:(?P<type>[a-zA-Z_][a-zA-Z0-9_]*))?(=(?P<default>[^}]*))?\}$')

   254

   255

    def __init__ (self, key, type_name, type, default) :

   256

        """

   257

            The given key is the name of this label's value.

   258

   259

            The given type_name is is None for the default type, otherwise the type's name. Type is a URLType.

   260

        """

   261

   262

        # type

   263

        self.type_name = type_name

   264

        self.type = type

   265

   266

        # store

   267

        self.key = key

   268

        self.default = default

   269

   270

    def match (self, value=None) :

   271

        """

   272

            Match -> LabelValue

   273

        """

   274

   275

        # default?

   276

        if value is None and self.default is not None :

   277

            return LabelValue(self, self.default, True)

   278

   279

        # only non-empty values!

   280

        elif value :

   281

            # test

   282

            if not self.type.test(value) :

   283

                return False

   284

   285

            # convert with type

   286

            value = self.type.parse(value)

   287

   288

            return LabelValue(self, value, False)

   289

   290

    def __str__ (self) :

   291

        return '{%s%s%s}' % (

   292

            self.key, 

   293

            (':%s' % (self.type_name, ) if self.type_name is not None else ''),

   294

            '=%s' % (self.default, ) if self.default is not None else '',

   295

        )

   296

   297

class URLType (object) :

   298

    """

   299

        Handles the type-ness of values in the URL

   300

    """

   301

   302

    def test (self, value) :

   303

        """

   304

            Tests if the given value is valid for this type.

   305

   306

            Defaults to calling parse(), and returning False on errors, True otherwise

   307

        """

   308

   309

        try :

   310

            self.parse(value)

   311

   312

        except :

   313

            return False

   314

   315

        else :

   316

            return True

   317

   318

    def parse (self, value) :

   319

        """

   320

            Parse the given value, which was tested earlier with test(), and return the value object

   321

        """

   322

   323

        abstract

   324

   325

    def append (self, old_value, value) :

   326

        """

   327

            Handle multiple values for this type, by combining the given old value and new value (both from parse).

   328

   329

            Defaults to raise an error

   330

        """

   331

   332

        raise URLError("Multiple values for argument")

   333

   334

    def build (self, obj) :

   335

        """

   336

            Reverse of parse(), return an url-value built from the given object

   337

        """

   338

   339

        abstract

   340

   341

    def build_multi (self, obj) :

   342

        """

   343

            Return a list of string values for the given object value (as from parse/append).

   344

   345

            Defaults to return [self.build(obj)]

   346

        """

   347

   348

        return [self.build(obj)]

   349

   350

class URLStringType (URLType) :

   351

    """

   352

        The default URLType, just plain strings.

   355

    """

   356

   357

    def parse (self, value) :

   358

        """

   359

            Identitiy

   360

        """

   361

   362

        return value

   363

   364

    def build (self, obj) :

   365

        return str(obj)

   366

   367

class URLIntegerType (URLType) :

   368

    """

   369

        A URLType for simple integers

   370

    """

   371

   372

    def __init__ (self, allow_negative=True, allow_zero=True, max=None) :

   373

        """

   374

            Pass in allow_negative=False to disallow negative numbers, allow_zero=False to disallow zero, or non-zero

   375

            max to specifiy maximum value

   376

        """

   377

   378

        self.allow_negative = allow_negative

   379

        self.allow_zero = allow_zero

   380

        self.max = max

   381

   382

    def _validate (self, value) :

   383

        """

   384

            Test to make sure value fits our criteria

   385

        """

   386

   387

        # negative?

   388

        if not self.allow_negative and value < 0 :

   389

            raise ValueError("value is negative")

   390

   391

        # zero?

   392

        if not self.allow_zero and value == 0 :

   393

            raise ValueError("value is zero")

   394

   395

        # max?

   396

        if self.max is not None and value > max :

   397

            raise ValueError("value is too large: %d" % value)

   398

   399

        return value

   400

   401

    def parse (self, value) :

   402

        """

   403

            Convert str -> int

   404

        """

   405

   406

        return self._validate(int(value))

   407

   408

    def build (self, obj) :

   409

        """

   410

            Convert int -> str

   411

        """

   412

   413

        return unicode(self._validate(obj))

   414

   415

class URLListType (URLType) :

   416

    """

   417

        A list of strings

   418

    """

   419

   420

    def parse (self, value) :

   421

        return [value]

   422

   423

    def append (self, old_value, value) :

   424

        return old_value + value

   425

   426

    def build_multi (self, obj) :

   427

        return obj

   428

   429

class URLConfig (object) :

   430

    """

   431

        Global configuration relevant to all URLs. This can be used to construct a set of URLs and then create an

   432

        URLTree out of them. Simply call the url_config() instace with the normal URL arguments (except, of course,

   433

        config), and finally just pass the url_config to URLTree (it's iterable).

   434

   435

        XXX: rename to URLFactory?

   436

    """

   437

   438

    # built-in type codes

   439

    BUILTIN_TYPES = {

   440

        # default - string

   441

        None    : URLStringType(),

   442

   443

        # string

   444

        'str'   : URLStringType(),

   445

   446

        # integer

   447

        'int'   : URLIntegerType(),

   448

   449

        # list of strs

   450

        'list'  : URLListType(),

   451

    }

   452

   453

    def __init__ (self, type_dict=None, ignore_extra_args=True) :

   454

        """

   455

            Create an URLConfig for use with URL

   456

   457

            If type_dict is given, it should be a dict of { type_names: URLType }, and they will be available for

   458

            type specifications in addition to the defaults. This will call type._init_name with the key, so do

   459

            *not* initialize the name yourself.

   460

   461

            If ignore_extra_args is given, unrecognized query arguments will be ignored.

   462

        """

   463

   464

        # build our type_dict

   465

        self.type_dict = self.BUILTIN_TYPES.copy()

   466

   467

        # apply the given type_dict

   468

        if type_dict :

   469

            # merge

   470

            self.type_dict.update(type_dict)

   471

   472

        # init

   473

        self.ignore_extra_args = ignore_extra_args

   474

        self.urls = []

   475

   476

    def get_type (self, type_name=None) :

   477

        """

   478

            Lookup an URLType by type_name, None for default.

   479

        """

   480

   481

        # lookup + return

   482

        return self.type_dict[type_name]

   483

   484

    def __call__ (self, *args, **kwargs) :

   485

        """

   486

            Return new URL object with this config and the given args, adding it to our list of urls

   487

        """

   488

   489

        # build

   490

        url = URL(self, *args, **kwargs)

   491

   492

        # store

   493

        self.urls.append(url)

   494

   495

        # return

   496

        return url

   497

   498

    def __iter__ (self) :

   499

        """

   500

            Returns all defined URLs

   501

        """

   502